diff --git a/docs/dev/index.rst b/docs/dev/index.rst index fb5c836..3e02148 100644 --- a/docs/dev/index.rst +++ b/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 `_. Elle est diponible librement sous licence GPLv3 +à l'adresse ``_. + +L'instance de production est accessible à l'adresse ``_. +Une instance de développement est accessible à l'adresse ``_. + +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 +``_. diff --git a/docs/dev/install.rst b/docs/dev/install.rst new file mode 100644 index 0000000..a5ebce1 --- /dev/null +++ b/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 `_. +Pour plus de détails sur la configuration pour le TFJM², voir +`la page dédiée à Docker`_. + +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 `_, + 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 ``_. +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``. diff --git a/docs/index.rst b/docs/index.rst index f059d49..85e63c1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,3 +20,4 @@ administrateur⋅rice. :caption: Développer dev/index + dev/install