Install documentation
Signed-off-by: Emmy D'Anello <emmy.danello@animath.fr>
This commit is contained in:
Emmy D'Anello
parent
2a85d4ff38
commit
21ff044044
GPG Key ID:
3A75C55819C8CF85
|
|
@ -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/>`_.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
dev/index
|
||||
dev/install
|
||||
|
|
|
|||
Loading…
Reference in New Issue