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``.