GeoNature Docker services

Ce dépôt permet de déployer automatiquement et facilement GeoNature, UsersHub dans un environnement dockerisé et accessible en HTTPS.

De plus, ce dépôt fournit une image Docker de GeoNature contenant les modules suivants :

• Occtax
• Occhab
• Validation
• Monitoring
• Dashboard
• Export

Principes et objectifs

1. GeoNature clé en main

Un fichier de configuration et une commande suffisent à déployer et mettre à jour facilement un environnement GeoNature dockerisé, fonctionnel et complet (GeoNature et ses principaux modules)

2. Modulaire et adaptable

Doit permettre à chacun d'adapter le projet pour ses besoins spécifiques et son infrastructure.

3. Limiter la complexité globale

Le projet ne doit pas inclure de fonctionnalités trop spécifiques à un contexte. L'ajout de fonctionnalités (paramètres, makefile...) ne doit pas se substituer à une maitrise de Docker, GeoNature ou d'administration système.

Démarrage rapide

1. Installation de Docker (Voir la documentation)

2. Ajout de votre utilisateur courant au groupe docker

   • Ajouter votre utilisateur courant dans le groupe docker : sudo usermod -aG docker $USER
   • Réouvrir sa session Linux pour appliquer les changements
   • Plus d'infos sur la documentation officielle

3. Installation de git

   • sudo apt-get install git

4. Clonage du dépôt de GeoNature-Docker-services : git clone https://github.com/PnX-SI/GeoNature-Docker-services ou extraire une archive

5. Déplacement dans le répertoire du dépôt : cd GeoNature-Docker-services

6. Création du fichier .env à partir du fichier d’exemple : cp .env.sample .env.

7. Changement des variables de configurations obligatoires dans le fichier .env. Les variables obligatoires sont les suivantes :

   • GEONATURE_DB_LOCAL_SRID : Code des projections des géométries stockées dans GeoNature (par défaut 2154)
   • POSTGRES_PASSWORD : Mot de passe de la base de données PostgreSQL
   • TRAEFIK_PASSWORD : Mot de passe de l'instance Traefik
   • DOCKER_UID et DOCKER_GID : Indique l'utilisateur utilisé par les conteneurs. Utiliser la commande id -u pour récupérer la valeur pour DOCKER_UID et id -g pour récupérer la valeur pour DOCKER_GID
   • ACME_EMAIL: Adresse mail utilisée pour la génération du certificat SSL par Let's Encrypt via traefik

8. Initialisation des fichiers de configurations. Lancer la commande ./init-config.sh afin de créer les dossiers et les fichiers de configuration requis. Le script init-config.sh génère aléatoirement aussi les clés secrètes pour GeoNature et UsersHub respectivement dans les fichiers suivants :

   • config/geonature/geonature_config.toml
   • config/usershub/config.py

9. Lancer la création des conteneurs Docker : docker compose up -d

Accéder aux logs

Les logs de tous les services sont accessibles avec la commande docker compose logs -f.

Pour n'afficher que les 100 dernières lignes, on utilise l'option --tail 100 et donc la commande docker compose logs -f --tail 100.

Pour n'afficher les logs que d'un service en particulier, on utilise la commande docker compose logs -f <nom du service>.

Les services

• postgres : la base de données
• usershub : la gestion des utilisateurs
• geonature-backend : l’API de GeoNature
• geonature-frontend : l’interface web de GeoNature
• geonature-worker : exécution de certaines tâches de GeoNature en arrière-plan (import, export, mail, etc...)
• redis : service de communication entre le worker et le backend
• traefik : serveur web redirigeant les requêtes vers le bon service

SERVICE              PORTS
geonature-backend    8000/tcp
geonature-frontend   80/tcp
geonature-worker     8000/tcp
postgres             0.0.0.0:5435->5432/tcp, :::5435->5432/tcp
redis                6379/tcp
traefik              0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, [::]:80->80/tcp, [::]:443->443/tcp
usershub             5001/tcp

Différents scénarios d'installation

Il est possible de déployer la stack GeoNature de plusieurs manières différentes. La configuration par défaut est pensée pour être autosuffisante, toutefois, dans le cas où vous voulez connecter cette stack à des outils déjà existant dans votre SI, plusieurs scénarios sont possibles.

Reverse Proxy externe

Si vous voulez utiliser votre propre Reverse Proxy (Nginx, Traefik ...), il est possible de déployer GeoNature sans Traefik.

Les configurations spécifiques à Traefik ont été déportées dans le fichier compose docker-compose.traefik.yml. Si on veut s'en passer, il faut modifier la variable COMPOSE_FILE du .env pour qu'elle n'utilise que le fichier docker-compose.essential.yml : COMPOSE_FILE=docker-compose.essential.yml.

Prenez soin de renseigner les variables d'environnement spécifiques à une utilisation hors Traefik (signalées par la mention "If you don't use traefik").

Base de données déportée

Si vous préférez stocker les données dans un SGBD externe, vous devrez enlever le profil db de la variable d'environnement COMPOSE_PROFILES. Il faudra ensuite renseigner les informations de connexion à votre base de données dans le .env (voir POSTGRES_HOST, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD).

[!INFO] Si vous voulez que les mises à jour de la base de données soient effectuées à chaque lancement de la stack Docker, ajouter le profil install-db dans COMPOSE_PROFILES.

Service UsersHub déjà existant :

Si pour d'autres besoins, vous disposez déjà d'un service UsersHub, vous devrez enlever le profil usershub de la variable d'environnement COMPOSE_PROFILES.

Configuration

Voir la documentation des différentes applications pour renseigner les fichiers de configuration :

• GeoNature : ./config/geonature/geonature_config.toml (fichier d’exemple)
• UsersHub : ./config/usershub/config.py (fichier d’exemple)

Ces fichiers doivent contenir a minima le paramètre SECRET_KEY.
Vous pouvez générer automatiquement des fichiers vierges contenant des clés secrètes aléatoires avec le script ./init-config.sh.

Si vous modifiez les fichiers de configuration de GeoNature, d'un de ses modules, de UsersHub, vous devez relancer les conteneurs Docker avec la commande docker compose restart (ou idéalement seulement le conteneur concerné, par exemple docker compose restart usershub).

À noter que certaines variables seront fournies en tant que variables d'environnement (voir les fichiers .env et docker-compose.yml), comme par exemple :

• URL_APPLICATION
• SQLALCHEMY_DATABASE_URI
• ...

Vous pouvez personnaliser la politique de redémarrage automatique des services en paramétrant la variable RESTART_POLICY du fichier .env (valeur par défaut: unless-stopped)

Il est aussi possible de personnaliser son installation en créant un fichier d'override de docker compose. Pour le détail de fonctionnement, voir la section Surcharger son installation.

Dossiers de configuration et de customisation

• Les fichiers de configuration de GeoNature, de ses modules et de UsersHub sont donc dans le dossier GeoNature-Docker-services/config/
• Les fichiers de customisation de GeoNature sont stockés dans le dossier GeoNature-Docker-services/data/geonature/custom/
• Les fichiers des médias de GeoNature (photos, application mobile...) sont stockés dans le dossier GeoNature-Docker-services/data/geonature/media/

Configuration par variable d’environnement

Les applications peuvent être configurées par des variables d’environnement préfixées respectivement par GEONATURE_ et USERSHUB_ (voir from_prefix_env).
Ces variables d’environnement doivent être renseignées directement dans le fichier docker-compose.yml, bien que certaines variables sont définies à partir d’une variable du même nom en provenance du fichier .env.

Mettre à jour GeoNature et ses modules

Pour récupérer la dernière version de GeoNature-docker-services :

1. Vérifiez si la dernière version disponible correspond aux versions des applications que vous souhaitez mettre à jour
2. Placez vous dans le dossier GeoNature-Docker-services de votre serveur
3. Mettez à jour le contenu du dossier dans sa dernière version : git fetch && git checkout <numéro de version>
4. Pour télécharger les nouvelles images et relancer la stack, il suffit de lancer la commande suivante : docker compose pull && docker compose up -d --remove-orphans

Warning

La variable SKIP_POPULATE_DB doit être à false pour appliquer les modifications de base de données provenant de la nouvelle version.

Note

Avec chaque release de GeoNature-docker-services, la version de l'image GeoNature est systématiquement modifiée dans le fichier docker-compose.essential.yml.

Note

Pour fixer la version de GeoNature, vous pouvez modifier les variables GEONATURE_BACKEND_EXTRA_IMAGE, GEONATURE_FRONTEND_EXTRA_IMAGE, et de UsersHub dans USERSHUB_IMAGE dans votre fichier .env. Par exemple, pour utiliser la version 2.15.3, effectuez les modifications suivantes :

USERSHUB_IMAGE="ghcr.io/pnx-si/usershub:2.4.4"
[...]
GEONATURE_BACKEND_EXTRA_IMAGE="ghcr.io/pnx-si/geonature-backend-extra:2.15.3"
[...]
GEONATURE_FRONTEND_EXTRA_IMAGE="ghcr.io/pnx-si/geonature-frontend-extra:2.15.3"

Monitoring

Installer un sous-module

1. Déposer le dossier contenant la configuration du protocole dans data/geonature/media/monitorings/. Par exemple :

   cp -r protocole_suivi/chiro data/geonature/media/monitorings/chiro

2. Lancer l'installation du sous-module avec la commande :

   docker compose exec geonature-backend geonature monitorings install <nom_sous_module>

Modifier ou mettre à jour le sous-module

Si vous souhaitez modifier le sous-module, faites le directement dans les fichiers du dossier du sous-module dans data/geonature/media/monitorings/.

Exécuter une commande Monitoring

Pour des actions plus avancées, vous pouvez vous attacher au Docker avec la commande docker compose exec geonature-backend bash et suivre la documentation du module Monitoring

Surcharger son installation

En fonction de l'environnement dans lequel vous déployez, il est possible que vous soyez amené à vouloir modifier le fichier docker-compose.yml afin de personnaliser le comportement de GDS. Afin de pouvoir mettre à jour votre repo, il est fortement conseillé de passer par un fichier d'override (voir documentation docker compose sur les overrides). Pour cela, vous pouvez créer un docker compose qui contient les modifications que vous souhaitez apporter à la stack et l'ajouter à votre variable d'environnement COMPOSE_FILE (voir documentation docker)

Plusieurs exemples de surcharge sont disponibles dans le dossier override_gallery. Ce dossier contient des fichiers compose.yml testés pour une version précise de GDS et permettant de modifier la configuration de GDS ou de déployer des services supplémentaires.

Lancer plusieurs instances de GDS sur le même serveur

Il existe de multiples façons de lancer plusieurs instances de GDS sur le même serveur.

En mode traefik, une méthode est présentée dans override_gallery/docker-compose.additional_stack.yml. Cette methode attribut un dossier à chaque instance de GDS, ce qui permet de les identifier facilement et évite les erreurs. C'est une implémentation assez simple, selon les contraintes de votre système, il est conseillé de l'adapter.

FAQ

Pour en savoir plus (lancer des commandes geonature, accéder à la BDD, intégrer le MNT, modifier votre domaine,...), consultez la FAQ GeoNature-Docker-services.

Pour des informations spécifiques sur le mode développement, voir la section Lancer une instance de développement et sa propre FAQ de développement.

Images Docker publiées

Une action Github permet la publication automatique d'images Docker frontend et backend de GeoNature sur les packages du dépôt :

• ghcr.io/pnx-si/geonature-frontend-extra
• ghcr.io/pnx-si/geonature-backend-extra

Ces images sont le pendant de celles publiées sur le dépôt de GeoNature mais contiennent en supplément les modules externes pré-cités en introduction.

Lancer une instance de développement

Commencez par vous assurer d'avoir installé make, jq et git-lfs sudo apt install make jq git-lfs openssl.

Il faut ensuite, dans votre fichier .env, décommenter les lignes de l'environnement de dev.

Une fois cela fait, il ne vous reste plus qu'à lancer make submodule_init, make build_images suivi de make dev. Il est déconseillé de lancer avec la commande docker compose up -d car si vous mettez à jour le projet GeoNature, cela ne fonctionnera pas sans relancer make dev_init. Le premier lancement peut mettre quelques dizaines de minutes le temps de build les images.

Vous pouvez accéder à votre GeoNature à l'adresse https://localhost/geonature et au proxy traefik http://localhost:8080/.

Exécuter les test Cypress

Vous devez avoir installé Cypress au préalable et lancé la stack. La commande make cypress vous permet ensuite de lancer les tests cypress.

Si vous voulez que vos tests s'exécutent comme dans la CI Github, il faut, une base sans données saisie au préalable. Puis, vous devez passer les migrations "samples" :

   geonature db upgrade occtax-samples-test@head
   geonature db upgrade occhab-samples@head
   geonature db upgrade import-samples@head`

Il est aussi possible de lancer Cypress en version headed ou avec des paramètres plus complexe en se calquant sur ce qui est fait dans le Makefile, par exemple pour lancer cypress en headed et en spécifiant les tests liés aux forms d'occtax :

source .env; cd sources/GeoNature/frontend; API_ENDPOINT="https://$${HOST}$${GEONATURE_BACKEND_PREFIX}/" URL_APPLICATION="https:$${HOST}$${GEONATURE_FRONTEND_PREFIX}/" cypress run --headed --spec cypress/e2e/occtax-form-spec.js

Liens utiles

GeoNature

• Dépôt
• Dockerfile backend
• Dockerfile frontend
• Dockerfile backend-extra
• Dockerfile frontend-extra

UsersHub

• Dépôt
• Dockerfile