mirror of
https://gitlab.com/animath/si/plateforme.git
synced 2025-11-04 04:22:14 +01:00
Install documentation
Signed-off-by: Emmy D'Anello <emmy.danello@animath.fr>
This commit is contained in:
Emmy D'Anello
@@ -2,3 +2,22 @@ Développer la plateforme
|
|||||||
========================
|
========================
|
||||||
|
|
||||||
Cette page est dédiée aux responsables informatiques qui cherchent à contribuer à 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/>`_.
|
||||||
|
|||||||
309
docs/dev/install.rst
Normal file
309
docs/dev/install.rst
Normal file
@@ -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``.
|
||||||
@@ -20,3 +20,4 @@ administrateur⋅rice.
|
|||||||
:caption: Développer
|
:caption: Développer
|
||||||
|
|
||||||
dev/index
|
dev/index
|
||||||
|
dev/install
|
||||||
|
|||||||
Reference in New Issue
Block a user