Go to file
ynerant 5c702187e5 Merge branch 'beta' into 'master'
Corrections diverses

See merge request bde/nk20!123
2020-09-14 10:16:13 +02:00
ansible Migrate LaTeX to XeTeX 2020-09-06 15:30:12 +02:00
apps The user validation form was ugly 2020-09-14 09:56:15 +02:00
locale Fix registration permissions and procedure 2020-09-14 09:49:30 +02:00
note_kfet JS was broken, please close your HTML tags 2020-09-13 23:18:00 +02:00
.dockerignore Some table accessors weren't updated 2020-09-01 19:04:35 +02:00
.env_example Revert to NOTE_URL 2020-08-09 18:39:17 +02:00
.gitignore We are in production, then we commit migrations 2020-09-05 10:05:17 +02:00
.gitlab-ci.yml Migrate LaTeX to XeTeX 2020-09-06 15:30:12 +02:00
.gitmodules 💩 Use HTTPS rather than SSH to clone nk20-scripts (may be reverted later) 2020-07-15 08:25:52 +02:00
COPYING Add COPYING 2019-07-08 07:58:44 +02:00
Dockerfile Migrate LaTeX to XeTeX 2020-09-06 15:30:12 +02:00
README.md Migrate LaTeX to XeTeX 2020-09-06 15:30:12 +02:00
entrypoint.sh Don't rebuild systematically migrations 2020-09-05 10:07:32 +02:00
manage.py and so it begins 2019-07-07 20:49:02 +00:00
nginx_note.conf_example Simplify NGINX examples 2020-08-09 20:33:48 +02:00
note.cron Human-readable activity wiki page should be updated in cron file 2020-09-06 11:11:02 +02:00
requirements.txt Update Django CAS server to 1.2.0 2020-09-06 09:41:32 +02:00
tox.ini Use flake8-django 2020-09-06 20:49:06 +02:00
uwsgi_note.ini Export activities in the Crans Wiki 2020-08-06 12:15:23 +02:00

README.md

NoteKfet 2020

License: GPL v3 pipeline status coverage report

Table des matières

Installation d'une instance de développement

L'instance de développement installe la majorité des dépendances dans un environnement Python isolé. Bien que cela permette de créer une instance sur toutes les distributions, cela veut dire que vos dépendances ne seront pas mises à jour automatiquement.

  1. Installation des dépendances de la distribution. Il y a quelques dépendances qui ne sont pas trouvable dans PyPI. On donne ci-dessous l'exemple pour une distribution basée sur Debian, mais vous pouvez facilement adapter pour ArchLinux ou autre.

    $ sudo apt update
    $ sudo apt install --no-install-recommends -y \
        ipython3 python3-setuptools python3-venv python3-dev \
        texlive-xetex gettext libjs-bootstrap4 fonts-font-awesome git
    
  2. Clonage du dépot là où vous voulez :

    $ git clone git@gitlab.crans.org:bde/nk20.git --recursive && cd nk20
    
  3. Création d'un environment de travail Python décorrélé du système. On n'utilise pas --system-site-packages ici pour ne pas avoir des clashs de versions de modules avec le système.

    $ python3 -m venv env
    $ source env/bin/activate  # entrer dans l'environnement
    (env)$ pip3 install -r requirements.txt
    (env)$ deactivate  # sortir de l'environnement
    
  4. Variable d'environnement. Copier le fichier .env_example vers .env à la racine du projet et mettre à jour ce qu'il faut.

  5. Migrations et chargement des données initiales. Pour initialiser la base de données avec de quoi travailler.

    (env)$ ./manage.py collectstatic --noinput
    (env)$ ./manage.py compilemessages
    (env)$ ./manage.py makemigrations
    (env)$ ./manage.py migrate
    (env)$ ./manage.py loaddata initial
    (env)$ ./manage.py createsuperuser  # Création d'un utilisateur initial
    
  6. Enjoy :

    (env)$ ./manage.py runserver 0.0.0.0:8000
    

En mettant 0.0.0.0:8000 après runserver, vous rendez votre instance Django accessible depuis l'ensemble de votre réseau, pratique pour tester le rendu de la note sur un téléphone !

Installation d'une instance de production

En production on souhaite absolument utiliser les modules Python packagées dans le gestionnaire de paquet. Cela permet de mettre à jour facilement les dépendances critiques telles que Django.

L'installation d'une instance de production néccessite une installation de Debian Buster ou d'Ubuntu 20.04.

Pour aller vite vous pouvez lancer le Playbook Ansible fournit dans ce dépôt en l'adaptant. Sinon vous pouvez suivre les étapes décrites ci-dessous.

  1. Sous Debian Buster, activer Debian Backports. En effet Django 2.2 LTS n'est que disponible dans les backports.

    $ echo "deb http://deb.debian.org/debian buster-backports main" | sudo tee /etc/apt/sources.list.d/deb_debian_org_debian.list
    
  2. Installation des dépendances APT. On tire les dépendances le plus possible à partir des dépôts de Debian. On a besoin d'un environnement LaTeX pour générer les factures.

    $ sudo apt update
    $ sudo apt install --no-install-recommends -t buster-backports -y \
        python3-django python3-django-crispy-forms \
        python3-django-extensions python3-django-filters python3-django-polymorphic \
        python3-djangorestframework python3-django-cas-server python3-psycopg2 python3-pil \
        python3-babel python3-lockfile python3-pip python3-phonenumbers ipython3 \
        python3-bs4 python3-setuptools \
        uwsgi uwsgi-plugin-python3 \
        texlive-xetex gettext libjs-bootstrap4 fonts-font-awesome \
        nginx python3-venv git acl
    
  3. Clonage du dépot dans /var/www/note_kfet,

    $ sudo mkdir -p /var/www/note_kfet && cd /var/www/note_kfet
    $ sudo chown www-data:www-data .
    $ sudo chmod g+rwx .
    $ sudo -u www-data git clone https://gitlab.crans.org/bde/nk20.git --recursive
    
  4. Création d'un environment de travail Python décorrélé du système.

    $ python3 -m venv env --system-site-packages
    $ source env/bin/activate  # entrer dans l'environnement
    (env)$ pip3 install -r requirements.txt
    (env)$ deactivate  # sortir de l'environnement
    
  5. Pour configurer UWSGI et NGINX, des exemples de conf sont disponibles. Modifier le fichier pour être en accord avec le reste de votre config

    $ cp nginx_note.conf_example nginx_note.conf
    $ sudo ln -sf /var/www/note_kfet/nginx_note.conf /etc/nginx/sites-enabled/
    

    Si l'on a un emperor (plusieurs instance uwsgi):

    $ sudo ln -sf /var/www/note_kfet/uwsgi_note.ini /etc/uwsgi/sites/
    

    Sinon si on est dans le cas habituel :

    $ sudo ln -sf /var/www/note_kfet/uwsgi_note.ini /etc/uwsgi/apps-enabled/
    

    Le touch-reload est activé par défault, pour redémarrer la note il suffit donc de faire touch uwsgi_note.ini.

  6. Base de données. En production on utilise PostgreSQL.

    $ sudo apt-get install postgresql postgresql-contrib
    

    La config de la base de donnée se fait comme suit:

    a. On se connecte au shell de psql

    $ sudo su - postgres
    $ psql
    

    b. On sécurise l'utilisateur postgres

    postgres=# \password
    Enter new password:
    

    Conservez ce mot de passe de la meme manière que tous les autres.

    c. On créer la basse de donnée, et l'utilisateur associé

    postgres=# CREATE USER note WITH PASSWORD 'un_mot_de_passe_sur';
    CREATE ROLE
    postgres=# CREATE DATABASE note_db OWNER note;
    CREATE DATABASE
    

    Si tout va bien :

    postgres=#\list
    List of databases
       Name    |  Owner   | Encoding |   Collate   |    Ctype    |   Access privileges   
    -----------+----------+----------+-------------+-------------+-----------------------
     note_db   | note     | UTF8     | fr_FR.UTF-8 | fr_FR.UTF-8 | 
     postgres  | postgres | UTF8     | fr_FR.UTF-8 | fr_FR.UTF-8 | 
     template0 | postgres | UTF8     | fr_FR.UTF-8 | fr_FR.UTF-8 | =c/postgres+postgres=CTc/postgres
     template1 | postgres | UTF8     | fr_FR.UTF-8 | fr_FR.UTF-8 | =c/postgres  +postgres=CTc/postgres
    (4 rows)
    
  7. Variable d'environnement et Migrations

    On copie le fichier .env_example vers le fichier .env à la racine du projet et on renseigne des secrets et des paramètres :

    DJANGO_APP_STAGE=dev # ou "prod" 
    DJANGO_DEV_STORE_METHOD=sqlite # ou "postgres"
    DJANGO_DB_HOST=localhost
    DJANGO_DB_NAME=note_db
    DJANGO_DB_USER=note
    DJANGO_DB_PASSWORD=CHANGE_ME
    DJANGO_DB_PORT=
    DJANGO_SECRET_KEY=CHANGE_ME
    DJANGO_SETTINGS_MODULE="note_kfet.settings
    NOTE_URL=localhost # URL où accéder à la note
    CONTACT_EMAIL=tresorerie.bde@localhost
    # Le reste n'est utile qu'en production, pour configurer l'envoi des mails
    NOTE_MAIL=notekfet@localhost
    EMAIL_HOST=smtp.localhost
    EMAIL_PORT=25
    EMAIL_USER=notekfet@localhost
    EMAIL_PASSWORD=CHANGE_ME
    WIKI_USER=NoteKfet2020
    WIKI_PASSWORD=CHANGE_ME
    

    Ensuite on (re)bascule dans l'environement virtuel et on lance les migrations

    $ source /env/bin/activate
    (env)$ ./manage.py check # pas de bêtise qui traine
    (env)$ ./manage.py migrate
    
  8. Enjoy \o/

Installation avec Docker

Il est possible de travailler sur une instance Docker.

Pour construire l'image Docker nk20,

git clone https://gitlab.crans.org/bde/nk20/ --recursive && cd nk20
docker build . -t nk20

Ensuite pour lancer la note Kfet en tant que vous (option -u), l'exposer sur son port 80 (option -p) et monter le code en écriture (option -v),

docker run -it --rm -u $(id -u):$(id -g) -v "$(pwd):/var/www/note_kfet/" -p 80:8080 nk20

Si vous souhaitez lancer une commande spéciale, vous pouvez l'ajouter à la fin, par exemple,

docker run -it --rm -u $(id -u):$(id -g) -v "$(pwd):/var/www/note_kfet/" -p 80:8080 nk20 python3 ./manage.py createsuperuser

Avec Docker Compose

On vous conseilles de faire un fichier d'environnement .env en prenant exemple sur .env_example.

Pour par exemple utiliser le Docker de la note Kfet avec Traefik pour réaliser le HTTPS,

nk20:
  build: /chemin/vers/le/code/nk20
  volumes:
    - /chemin/vers/le/code/nk20:/var/www/note_kfet/
  env_file: /chemin/vers/le/code/nk20/.env
  restart: always
  labels:
    - "traefik.http.routers.nk20.rule=Host(`ndd.example.com`)"
    - "traefik.http.services.nk20.loadbalancer.server.port=8080"

Documentation

Le cahier des charges initial est disponible sur le Wiki Crans.

La documentation des classes et fonctions est directement dans le code et est explorable à partir de la partie documentation de l'interface d'administration de Django. Commentez votre code !

La documentation plus haut niveau sur le développement est disponible sur le Wiki associé au dépôt Git.

FAQ

Regénérer les fichiers de traduction

Pour regénérer les traductions vous pouvez vous placer à la racine du projet et lancer le script makemessages. Il faut penser à ignorer les dossiers ne contenant pas notre code, dont le virtualenv.

django-admin makemessages -i env

Une fois les fichiers édités, vous pouvez compiler les nouvelles traductions avec

django-admin compilemessages