Install documentation

Signed-off-by: Emmy D'Anello <emmy.danello@animath.fr>

docs/dev/index.rst

@@ -2,3 +2,22 @@ Développer la plateforme
 ========================
 
 Cette page est dédiée aux responsables informatiques qui cherchent à contribuer à la plateforme.
+
+Présentation
+------------
+
+La plateforme d'inscription du TFJM² actuelle est née lors de l'édition 2020. Elle n'est
+pas la première à exister, elle succède à une précédente, moins fonctionnelle, dont les
+sources ont été perdues. Elle a été développée par Emmy D'Anello, bénévole pour Animath,
+qui la maintient au moins jusqu'en 2024.
+
+La plateforme est développée en Python, utilisant le framework web
+`Django <https://www.djangoproject.com/>`_. Elle est diponible librement sous licence GPLv3
+à l'adresse `<https://gitlab.com/animath/si/plateforme-tfjm>`_.
+
+L'instance de production est accessible à l'adresse `<https://inscription.tfjm.org/>`_.
+Une instance de développement est accessible à l'adresse `<https://inscription-dev.tfjm.org/>`_.
+
+Les deux instances sont hébergées sur le serveur d'Animath. La documentation spécifique
+à l'installation des services d'Animath peut être trouvée à l'adresse
+`<https://doc.animath.live/>`_.

docs/dev/install.rst

@@ -0,0 +1,309 @@
+Installation de la plateforme du TFJM²
+======================================
+
+Cette page documente la procédure d'installation de la plateforme du TFJM²,
+aussi bien dans un environnement de développement que de production.
+
+
+Installation en production
+--------------------------
+
+Installation de Docker
+""""""""""""""""""""""
+
+Les outils du TFJM² sont déployés en utilisant `Docker <https://www.docker.com/>`_.
+Pour plus de détails sur la configuration pour le TFJM², voir
+`la page dédiée à Docker<docker.html>`_.
+
+Commencez par installer Docker et Docker-Compose (qui sont a priori déjà installés
+sur la plateforme du TFJM²), en commençant par installer le dépôt APT de Docker :
+
+.. code-block:: bash
+
+    # Add Docker's official GPG key:
+    sudo apt update
+    sudo apt install ca-certificates curl gnupg
+    curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
+    sudo chmod a+r /usr/share/keyrings/docker-archive-keyring.gpg
+
+    # Add the repository to Apt sources:
+    echo \
+      "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
+      $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
+      sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+    sudo apt update
+
+    sudo apt install docker-ce docker-compose-plugin
+
+Installation de la plateforme
+"""""""""""""""""""""""""""""
+
+Dans le fichier ``docker-compose.yml``, configurer :
+
+.. code-block:: yaml
+
+    version: "3.8"
+    services:
+      # […]
+      inscription:
+        build: https://gitlab.com/animath/si/plateforme.git
+        links:
+          - postgres
+          - redis
+          - elasticsearch
+        env_file:
+          - ./secrets/inscription.env
+        restart: always
+        volumes:
+          - "./data/inscription/media:/code/media"
+          - "/etc/localtime:/etc/localtime:ro"
+        networks:
+          - tfjm
+        labels:
+          - "traefik.http.routers.inscription-tfjm2.rule=Host(`inscription.tfjm.org`, `plateforme.tfjm.org`)"
+          - "traefik.http.routers.inscription-tfjm2.entrypoints=websecure"
+          - "traefik.http.routers.inscription-tfjm2.tls.certresolver=mytlschallenge"
+
+      postgres:
+        image: postgres:16
+        volumes:
+          - "./data/postgresql_16:/var/lib/postgresql/data"
+        restart: always
+        env_file:
+          - ./secrets/postgres.env
+        networks:
+          - tfjm
+
+      redis:
+        image: redis:alpine
+        restart: always
+        networks:
+          - tfjm
+
+      elasticsearch:
+        image: docker.elastic.co/elasticsearch/elasticsearch:7.17.9
+        restart: always
+        env_file:
+          - ./secrets/elasticsearch.env
+        networks:
+          - tfjm
+      # […]
+
+En cas d'instance de pré-production, il est possible de changer de branche en
+rajoutant par exemple ``#dev`` à la fin de l'URL.
+
+Les différents paramètres peuvent être modifiés si nécessaire, à commencer par les
+versions des autres services (PostgreSQL, Redis, Elasticsearch). Penser à mettre à jour
+cette documentation en cas de mise à jour future. Il est attendu d'avoir un réseau
+``tfjm`` configuré :
+
+.. code-block:: yaml
+
+    networks:
+    tfjm:
+      driver: bridge
+
+L'URL utilisée peut être modifiée en changeant les options de Traefik, section ``labels``.
+
+Configuration
+"""""""""""""
+
+La configuration se fait essentiellement dans les fichiers d'environnement.
+
+Pour la base de données, une seule variable d'environnement est requise :
+``POSTGRES_PASSWORD``, qui correspond au mot de passe maître de PostgreSQL.
+
+Les variables d'environnement de ElasticSearch se résume à du paramétrage de mémoire :
+
+.. code-block:: bash
+
+    discovery.type=single-node
+    ES_JAVA_OPTS=-Xms512m -Xmx512m
+
+Redis n'a pas besoin de configuration particulière.
+
+Enfin, pour la plateforme elle-même, il faut configurer les variables suivantes :
+
+.. code-block:: bash
+
+    TFJM_STAGE=prod
+    DJANGO_SECRET_KEY=
+    DJANGO_DB_TYPE=PostgreSQL
+    DJANGO_DB_HOST=postgres
+    DJANGO_DB_PORT=
+    DJANGO_DB_NAME=
+    DJANGO_DB_USER=
+    DJANGO_DB_PASSWORD=
+    REDIS_SERVER_HOST=redis
+    REDIS_SERVER_PORT=6379
+    SMTP_HOST=ssl0.ovh.net
+    SMTP_PORT=465
+    SMTP_HOST_USER=contact@tfjm.org
+    SMTP_HOST_PASSWORD=
+    FROM_EMAIL=Contact TFJM²
+    SERVER_EMAIL=contact@tfjm.org
+    HAYSTACK_INDEX_NAME=inscription-tfjm
+    SYMPA_HOST=lists.tfjm.org
+    SYMPA_URL=lists.tfjm.org/sympa
+    SYMPA_EMAIL=contact@tfjm.org
+    SYMPA_PASSWORD=
+    HELLOASSO_CLIENT_ID=
+    HELLOASSO_CLIENT_SECRET=
+
+* ``TFJM_STAGE`` : ``prod`` ou ``dev``. ``prod`` est utilisé pour la production,
+  ``dev`` pour le développement ou pré-production. Permet de désactiver certaines
+  fonctionnalités de production, notamment l'envoi de mails, le cache Redis, les listes
+  de diffusion, et d'activer le débogage. Les erreurs seront ainsi directement affichées
+  en développement tandis qu'elles seront envoyées par mail en production.
+* ``DJANGO_SECRET_KEY`` : correspond à
+  `la clé secrète Django <https://docs.djangoproject.com/fr/5.0/ref/settings/#secret-key>`_,
+  permettant de signer les sessions et les cookies. Il est important de la garder secrète.
+  Pour la générer, il est possible d'utiliser la commande
+  ``python3 manage.py generate_secret_key``.
+* ``DJANGO_DB_TYPE`` : Le type de base de données à utiliser, parmi
+  ``PostgreSQL``, ``MySQL`` et ``SQLite``. ``SQLite`` n'est à utiliser qu'en développement
+  local.
+* ``DJANGO_DB_HOST`` : L'hôte de la base de données pour les bases de données
+  ``PostgreSQL`` et ``MySQL``. Pour ``SQLite``, il faut mettre le chemin vers le fichier
+  de base de données. Dans l'exemple ci-dessus, ``postgres`` est l'hôte Docker.
+* ``DJANGO_DB_PORT`` : Le port de la base de données. (PostgreSQL ou MySQL uniquement)
+  Si laissé vide, utilisera le port par défaut du service, ``5432`` pour PostgreSQL et
+  ``3306`` pour MySQL.
+* ``DJANGO_DB_NAME`` : Le nom de la base de données. (PostgreSQL ou MySQL uniquement)
+* ``DJANGO_DB_USER`` : Le nom d'utilisateur de la base de données.
+  (PostgreSQL ou MySQL uniquement)
+* ``DJANGO_DB_PASSWORD`` : Le mot de passe de la base de données.
+  (PostgreSQL ou MySQL uniquement)
+* ``REDIS_SERVER_HOST`` : L'hôte de Redis (en production uniquement). Dans l'exemple
+  ci-dessus, ``redis`` est l'hôte Docker.
+* ``REDIS_SERVER_PORT`` : Le port de Redis (en production uniquement). Si laissé vide,
+  utilisera le port par défaut du service, ``6379``.
+* ``SMTP_HOST`` : L'hôte du serveur SMTP à utiliser pour envoyer les mails. Utilise par
+  défaut le serveur d'OVH.
+* ``SMTP_PORT`` : Le port du serveur SMTP à utiliser pour envoyer les mails.
+* ``SMTP_HOST_USER`` : Le nom d'utilisateur du serveur SMTP à utiliser pour envoyer les
+  mails. Correspond à l'identifiant OVH.
+* ``SMTP_HOST_PASSWORD`` : Le mot de passe du serveur SMTP à utiliser pour envoyer les
+  mails. Correspond au mot de passe OVH.
+* ``FROM_EMAIL`` : Le nom lisible à utiliser comme expéditeur des mails
+  (défaut : Contact TFJM²).
+* ``SERVER_EMAIL`` : L'adresse mail à utiliser comme expéditeur des mails
+  (défaut : contact@tfjm.org).
+* ``HAYSTACK_INDEX_NAME`` : Le nom de l'index ElasticSearch à utiliser pour les recherches
+  dans ElasticSearch (défaut : inscription-tfjm).
+* ``SYMPA_HOST`` : Le domaine des listes de diffusion Sympa utilisé.
+* ``SYMPA_URL`` : L'URL du serveur Sympa à utiliser pour gérer les listes de diffusion.
+* ``SYMPA_EMAIL`` : L'adresse mail à utiliser pour se connecter à Sympa.
+* ``SYMPA_PASSWORD`` : Le mot de passe à utiliser pour se connecter à Sympa.
+* ``HELLOASSO_CLIENT_ID`` : L'identifiant client HelloAsso à utiliser pour gérer les
+  paiements HelloAsso.
+* ``HELLOASSO_CLIENT_SECRET`` : Le secret client HelloAsso à utiliser pour gérer les
+  paiements HelloAsso. Doit être maintenu secret.
+
+Installation de la base de données
+""""""""""""""""""""""""""""""""""
+
+Pour gérer la base de données PostgreSQL, on peut utiliser les commandes suivantes :
+
+.. code-block:: bash
+
+    sudo docker compose up -d postgres
+    sudo docker compose exec -u postgres postgres createuser -P inscription_tfjm  # Création du compte `inscription_tfjm` en demander un mot de passe. À ne faire qu'une seule fois
+    sudo docker compose exec -u postgres postgres createdb -O inscription_tfjm inscription_tfjm  # Création de la base de données `inscription_tfjm` en utilisant le compte `inscription_tfjm`
+    sudo docker compose exec -u postgres pg_dump inscription_tfjm > inscription_tfjm.sql  # Pour sauvegarder la base de données `inscription_tfjm`
+    sudo docker compose exec -u postgres dropdb inscription_tfjm  # Pour supprimer la base de données `inscription_tfjm`
+
+La suppression et la recréation sont utiles en cas de réinitialisation annuelle de la base
+de données.
+
+
+Lancement
+"""""""""
+
+Pour lancer la plateforme, il suffit de lancer la commande suivante :
+
+.. code-block:: bash
+
+    sudo docker compose up -d inscription
+
+Pour arrêter la plateforme, il suffit de lancer la commande suivante :
+
+.. code-block:: bash
+
+    sudo docker compose stop inscription
+
+En cas de mise à jour de la plateforme, il suffit de lancer la commande suivante :
+
+.. code-block:: bash
+
+    sudo docker compose up -d --build inscription
+
+Selon le principe de Docker, les données sont conservées dans un volume Docker, ici
+dans le dossier ``data/inscription``. Le reste est volatile, puisqu'il peut être recréé
+à partir du code source. Attention donc de ne pas coder en production (ce qui est de toute
+façon à proscrire !).
+
+Les migrations de base de données sont automatiquement appliquées au lancement de la
+plateforme, de même que la collecte de fichiers statiques ou encore la génération de la
+documentation. Il n'y a rien à faire de spécial post-lancement, si ce n'est vérifier que
+tout fonctionne correctement.
+
+
+Installation en développement
+-----------------------------
+
+L'installation sur une machine locale est plus légère et est utile pour pouvoir tester
+rapidement.
+
+Commencez par récupérer le code source de la plateforme :
+
+.. code-block:: bash
+
+    git clone https://gitlab.com/animath/si/plateforme-tfjm.git
+    cd plateforme-tfjm
+
+Afin de pouvoir isoler l'environnement de développement, il est conseillé d'utiliser
+un environnement virtuel Python. Commencez alors par installer Python (si ce n'est pas
+déjà fait, au moins en version 3.10) ainsi que ``virtualenv``, puis vous pouvez créer
+l'environnement virtuel, et entrer dedans :
+
+.. code-block:: bash
+
+    python3 -m venv venv
+    source venv/bin/activate
+
+Il vous faut ensuite installer les dépendances de la plateforme :
+
+.. code-block:: bash
+
+    pip install -r requirements.txt
+
+Pour exécuter des tests, il est nécessaire d'installer ``tox`` en supplément.
+
+Ensuite, vous devez initialiser la base de données locale (qui sera stockée dans un
+fichier SQLite ``db.sqlite3``) :
+
+.. code-block:: bash
+
+    python3 manage.py migrate
+
+Enfin, vous pouvez lancer la plateforme :
+
+.. code-block:: bash
+
+    python3 manage.py runserver
+
+Vous pouvez alors accéder à la plateforme à l'adresse `<http://localhost:8000/>`_.
+Elle se recharge automatiquement à chaque modification du code source, inutile de la
+relancer.
+
+Pour arrêter la plateforme, il suffit d'appuyer sur ``Ctrl+C`` dans le terminal.
+
+Pour vous créer un compte administrateur⋅rice, il suffit de lancer la commande suivante :
+
+.. code-block:: bash
+
+    python3 manage.py createsuperuser
+
+En cas de problème, vous pouvez librement supprimer la base de données locale et la
+recréer en réexécutant la commande ``python3 manage.py migrate``.

docs/index.rst

@@ -20,3 +20,4 @@ administrateur⋅rice.
    :caption: Développer
 
    dev/index
+   dev/install