Merge pull request #13 from PnX-SI/doc-review-010

Doc review / 0.1.0

README.md

@@ -1,7 +1,7 @@
 # GeoNature Docker Services
 
-Ce dépôt permet de déployer GeoNature, UsersHub et TaxHub dans un environnement dockerisé.
-De plus, celui-ci fournit une image Docker de GeoNature contenant, outre les modules du cœur (OccTax, OccHab, Validation), les modules suivants :
+Ce dépôt permet de déployer automatiquement GeoNature, UsersHub et TaxHub dans un environnement dockerisé et accessible en HTTPS.  
+De plus, celui-ci fournit une image Docker de GeoNature contenant, outre les modules du cœur (Occtax, Occhab, Validation), les modules suivants :
 
 - [Import](https://github.com/PnX-SI/gn_module_import)
 - [Export](https://github.com/PnX-SI/gn_module_exports)
@@ -15,14 +15,14 @@ De plus, celui-ci fournit une image Docker de GeoNature contenant, outre les mod
 - Ajouter votre utilisateur courant au groupe `docker` : `sudo usermod -aG docker $USER` puis réouvrir sa session Linux ([voir la documentation](https://docs.docker.com/engine/install/linux-postinstall))
 - Clôner le dépôt : `git clone https://github.com/PnX-SI/GeoNature-Docker-services` ou extraire une [archive](https://github.com/PnX-SI/GeoNature-Docker-services/releases)
 - Se placer dans le répertoire du dépôt : `cd GeoNature-Docker-services`
-- Créer le fichier `.env` à partir du fichier d’exemple : `cp .env.sample .env`. Compléter les paramètres importants.
+- Créer le fichier `.env` à partir du fichier d’exemple : `cp .env.sample .env`. Compléter les paramètres importants (`HOST`, `ACME_EMAIL`, `GEONATURE_LOCAL_SRID`, `POSTGRES_PASSWORD`).
 - Lancer la commande `./init-config.sh` afin de créer les ficiers de configuration suivant, avec des clés secrètes générées aléatoirement :
   - `config/geonature/geonature_config.toml`
   - `config/usershub/config.py`
   - `config/taxhub/config.py`
 - Lancer les conteneurs : `docker compose up -d`
 
-Les logs sont accessibles avec la commande `docker compose logs -f` ou `docker compose -f <nom du service>`.
+Les logs sont accessibles avec la commande `docker compose logs -f` ou `docker compose -f <nom du service>` (avec l'option `-n100` pour ne renvoyer que les 100 dernières lignes des logs).
 
 
 ## Les services
@@ -32,9 +32,9 @@ Les logs sont accessibles avec la commande `docker compose logs -f` ou `docker c
  - `taxhub` : la gestion du référentiel taxonomique
  - `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...)
+ - `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 redirigant les requêtes vers le bon service
+ - `traefik` : serveur web redirigeant les requêtes vers le bon service
 
 ```
 SERVICE              PORTS
@@ -59,30 +59,46 @@ Voir la documentation des différentes applications pour renseigner les fichiers
 - UsersHub : `./config/usershub/config.py` ([fichier d’exemple](https://github.com/PnX-SI/UsersHub/tree/master/config/config.py.sample))
 - TaxHub : `./config/taxhub/config.py` ([fichier d’exemple](https://github.com/PnX-SI/TaxHub/apptax/config.py.sample))
 
-Ces fichiers doivent contenir *a minima* le paramètre `SECRET_KEY`.
-Vous pouvez générer des fichiers vierges contenant des clés secrètes aléatoire avec le script `./init-config.sh`.
+Ces fichiers doivent contenir *a minima* le paramètre `SECRET_KEY`.  
+Vous pouvez générer des fichiers vierges contenant des clés secrètes aléatoires avec le script `./init-config.sh`.
 
-À noter que certaines variables seront fournies en tant que variables d'environnement (voir les fichiers [`.env`](./.env.sample) et [`docker-compose.yml`](./docker-compose.yml)), comme par exemple:
-  - `URL_APPLICATION`
-  - `SQLALCHEMY_DATABASE_URI`
-  - ...
+À noter que certaines variables seront fournies en tant que variables d'environnement (voir les fichiers [`.env`](./.env.sample) et [`docker-compose.yml`](./docker-compose.yml)), comme par exemple :
 
+- `URL_APPLICATION`
+- `SQLALCHEMY_DATABASE_URI`
+- ...
+
+### Dossiers de configuration et de customisation
+
+- Les fichiers de configuration de GeoNature et de ses modules, de TaxHub 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ée respectivement par `GEONATURE_`, `TAXHUB_` et `USERSHUB_` (voir [from_prefix_env](https://flask.palletsprojects.com/en/2.2.x/api/#flask.Config.from_prefixed_env)).
-Ces variables d’environnement doivent être renseigné 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`.
+Les applications peuvent être configurées par des variables d’environnement préfixées respectivement par `GEONATURE_`, `TAXHUB_` et `USERSHUB_` (voir [from_prefix_env](https://flask.palletsprojects.com/en/2.2.x/api/#flask.Config.from_prefixed_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
+
+- Vérifiez si la [dernière version disponible](https://github.com/PnX-SI/GeoNature-Docker-services/releases) correspond aux versions des applications que vous souhaitez mettre à jour
+- Placez vous dans le dossier `GeoNature-Docker-services` de votre serveur
+- Mettez à jour le contenu du dossier dans sa dernière version : `git pull`
+- Lancez la commande qui va télécharger les dernières versions des différentes applications et les relancer : `docker compose pull && docker compose up -d`
+
+## FAQ
+
+Pour en savoir plus (lancer des commandes `geonature`, accéder à la BDD, intégrer le MNT, modifier votre domaine,...), consultez la [FAQ](https://github.com/PnX-SI/GeoNature-Docker-services/blob/main/docs/faq.md).
 
-## Images publiées
+## Images Docker publiées
 
-Une actions permet la publication d'image frontend et backend dockers sur [les packages du dépôt](https://github.com/orgs/PnX-SI/packages?repo_name=GeoNature-Docker-services] :
+Une action permet la publication automatique d'images Docker frontend et backend de GeoNature sur [les packages du dépôt](https://github.com/orgs/PnX-SI/packages?repo_name=GeoNature-Docker-services) :
 
 - `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](https://github.com/orgs/PnX-SI/packages?repo_name=GeoNature) mais contiennent en supplément les modules externes pré-cités en introduction.
 
-
 ## Liens utiles
 
 ### Geonature
@@ -93,16 +109,12 @@ Ces images sont le pendant de [celles publiées sur le dépôt de GeoNature](htt
 - [`Dockerfile` backend-extra](./build/Dockerfile-geonature-backend)
 - [`Dockerfile` frontend-extra](./build/Dockerfile-geonature-frontend)
 
-
 ### UsersHub
 
 - [Dépôt](https://github.com/PnX-SI/UsersHub)
 - [`Dockerfile`](https://github.com/PnX-SI/UsersHub/blob/master/Dockerfile)
 
-
 ### TaxHub
 
 - [Dépôt](https://github.com/PnX-SI/Taxhub)
 - [`Dockerfile`](https://github.com/PnX-SI/TaxHub/blob/master/Dockerfile)
-
-

docs/changelog.md

@@ -1,18 +1,17 @@
 CHANGELOG
 =========
 
-0.0.1 (unreleased)
+0.1.0 (2023-09-15)
 ------------------
 
-**Versions**
+Première version fonctionnelle de GeoNature-Docker-services, permettant de déployer, avec un seul fichier `docker-compose`, GeoNature et ses 4 modules externes principaux, TaxHub, UsersHub et traefik (comme reverse proxy et pour gérer les certificats SSL, générés automatiquement pour que les applications soient accessibles en HTTPS lors de leur installation).
 
-```
-GDS_VERSION=0.0.1
-TAXHUB_VERSION=1.11.1
-USERSHUB_VERSION=2.3.3
-GEONATURE_VERSION=2.12.3
-GN_MODULE_DASHBOARD=1.4.0
-GN_MODULE_EXPORT=1.6.0
-GN_MODULE_IMPORT=2.2.0
-GN_MODULE_MONITORING=0.7.0
-```
+**🏷️ Versions**
+
+- GeoNature 2.12.3
+- TaxHub 1.12.1
+- UsersHub 2.3.4
+- GeoNature-dashboard 1.4.0
+- GeoNature-export1.6.0
+- GeoNature-import 2.2.1
+- GeoNature-monitoring 0.7.0

docs/faq.md

@@ -1,6 +1,21 @@
 # FAQ
 
-## Comment accéder à la base de données ?
+## Comment lancer des commandes `geonature` ?
+
+Pour exécuter une commande `geonature`, lancer la commande :
+
+```
+docker compose exec -it geonature-backend geonature nom_de_la_commande
+```
+
+Exemples : 
+
+```
+docker compose exec -it geonature-backend geonature --help
+docker compose exec -it geonature-backend geonature dashboard refresh-vm
+```
+
+## Comment ouvrir à l'accès à la base de données ?
 
 Créer un fichier `docker-compose.override.yml` contenant :
 
@@ -13,15 +28,15 @@ services:
 
 puis re-lancer `docker compose up -d`
 
-Il se peut que vous ayez déjà une base de données localement.
-Dans ce cas, vous pouvez utiliser un autre port : ` -5433:5432`
-La base de données sera alors accessible localement sur le port 5433.
+Il se peut que vous ayez déjà une base de données localement.  
+Dans ce cas, vous pouvez utiliser un autre port : `-5433:5432`.  
+La base de données sera alors accessible localement sur le port 5433.  
 Attention, le deuxième port est celui d’écoute dans le conteneur et doit rester à 5432.
 
 
 ## Comment déployer GeoNature, TaxHub et UsersHub sur des domaines séparés ?
 
-Éditer le fichier `.env` comme ceci (on suppose que ``HOST="mon-domaine.org") :
+Modifier le fichier `.env` comme ceci (on suppose que `HOST="mon-domaine.org"`) :
 
 ```
 USERSHUB_HOST="usershub.${HOST}"
@@ -42,18 +57,22 @@ GEONATURE_FRONTEND_HOSTPORT="geonature.${HOSTPORT}"
 GEONATURE_FRONTEND_PREFIX="/"
 ```
 
-puis relancer `docker compose up -d`
+Puis relancer `docker compose up -d`
+
+Vous pourrez alors accéder, par exemple, à GeoNature à l’adresse https://geonature.mon-domaine.org.
+
 
-Vous pourrez alors accéder, par exemple, à GeoNature à l’adresse https://geonature.mon-domaine.org
+## Comment importer le MNT / DEM ?
 
+GeoNature a besoin d'un modèle numérique de terrain (MNT ou DEM) dans sa base de données pour calculer automatiquement les altitudes des objets localisés sur les cartes.
 
-## Comment peupler le MNT / DEM ?
+Par défaut un MNT de France métropolitaine avec un pas de 250m fourni par l'IGN est proposé et peut être intégré dans la base de données. Il est possible (et recommandé) de le remplacer par un MNT plus précis limité à votre territoire.
 
-- Télécharger la dernière version de la BD ALTI (24MB): `wget https://geonature.fr/data/ign/BDALTIV2_2-0_250M_ASC_LAMB93-IGN69_FRANCE_2017-06-21.zip`
+- Télécharger la version de la BD ALTI IGN (24MB) proposée par défaut : `wget https://geonature.fr/data/ign/BDALTIV2_2-0_250M_ASC_LAMB93-IGN69_FRANCE_2017-06-21.zip`
 - Désarchiver : `unzip BDALTIV2_2-0_250M_ASC_LAMB93-IGN69_FRANCE_2017-06-21.zip`
-- Installer `raster2pgsql` : `docker compose exec postgres /bin/sh -c "apt-get update && apt-get install -y postgis"`
-- Copier le MNT dans le conteneur : `docker compose cp BDALTIV2_250M_FXX_0098_7150_MNT_LAMB93_IGN69.asc postgres:/`
+- Installer `raster2pgsql` dans le conteneur Docker contenant PostgreSQL et la BDD de GeoNature : `docker compose exec postgres /bin/sh -c "apt-get update && apt-get install -y postgis"`
+- Copier le MNT dans ce conteneur : `docker compose cp BDALTIV2_250M_FXX_0098_7150_MNT_LAMB93_IGN69.asc postgres:/`
 - Lancer l’import (préciser votre SRID) : `docker compose exec postgres raster2pgsql -s {local_srid} -c -C -I -M -d BDALTIV2_250M_FXX_0098_7150_MNT_LAMB93_IGN69.asc ref_geo.dem | docker compose exec -T postgres psql -U geonatadmin -d geonature2db`
 
-À noter : si le conteneur `postgres` est re-créé, l’installation de `raster2pgsql` et la copie du MNT dans le conteneur seront perdu.
-Mais ces données ne sont normalement plus nécessaire une fois le MNT importé en base (qui elle est permanante).
+À noter : si le conteneur `postgres` est re-créé, l’installation de `raster2pgsql` et la copie du MNT dans le conteneur seront perdus.  
+Mais ces données ne sont normalement plus nécessaires une fois le MNT importé dans la base de données (qui elle est permanente).