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<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 :

# 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 :

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é :

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 :

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 :

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 :

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 :

sudo docker compose up -d inscription

Pour arrêter la plateforme, il suffit de lancer la commande suivante :

sudo docker compose stop inscription

En cas de mise à jour de la plateforme, il suffit de lancer la commande suivante :

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 :

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 :

python3 -m venv venv
source venv/bin/activate

Il vous faut ensuite installer les dépendances de la plateforme :

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) :

python3 manage.py migrate

Enfin, vous pouvez lancer la plateforme :

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 :

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.