Ce tutoriel détaille les étapes d'installation globale de Geonature en mode Développement.

Documentation officielle (pour installer en Production)

Les applications suivantes seront installées :

• GeoNature
• TaxHub qui pilote le schéma taxonomie
• UsersHub qui pilote le schéma utilisateurs

GeoNature repose sur les composants suivants :

• PostgreSQL / PostGIS
• Python 3 et dépendances Python nécessaires à l’application
• Flask (framework web Python)
• Apache
• Angular 7, Angular CLI, NodeJS
• Librairies javascript (Leaflet, ChartJS)
• Librairies CSS (Bootstrap, Material Design)

Ressources minimum serveur :

• Un serveur Debian 10 ou Debian 11 architecture 64-bits
• 4 Go RAM
• 20 Go d’espace disque

Pour connecter directement votre machine à votre compte Github et ainsi éviter de devoir se reconnecter à chaque fois, vous pouvez renseigner votre clé SSH dans les paramètres de Github.

1. Trouver sa clé SSH à partir du terminal vi ~/.ssh/id_rsa.pub Copier ce qui s'affiche sur le terminal

2. Renseigner la clé SSH sur Github

• Github --> Settings --> SSH and GPG Keys --> New SSH Key
• Coller la clé SSH et renseigner le nom de votre machine en tant que titre (ex: pcp-hoarau)

Fonctionnement de Github

source : http://justinbois.github.io/bootcamp/2021/lessons/l12_version_control_with_git.html

1. Se rendre sur le dépôt Geonature
2. Cliquer sur Fork (en haut à droite de la page Github)

1. Se placer dans le répertoire du dépôt local cd ~/workspace/geonature/web/

2. Récupérer la clé SSH du dépôt distant (copier)

3. Cloner le dépôt distant dans le dépôt local git clone [email protected]:ch-cbna/geonature.git

Vous devez indiquer le dépôt upstream(amont) dans Git pour synchroniser les modifications que vous faites dans votre Fork avec le dépôt original.

a. Lister le dépôt distant actuellement configuré pour votre fork. $ git remote -v

b. Spécifier un nouveau dépôt upstream distant qui sera synchronisé avec le fork. git remote add upstream https://github.com/PnX-SI/GeoNature.git

c. Vérifier le nouveau dépôt upstream que vous avez spécifié pour votre fork. $ git remote -v

Source : https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork

• Synchronisation du dépôt local à partir du parent distant $ gh repo sync

• Synchronisation du dépôt local à partir du parent distant sur une branche spécifique $ gh repo sync --branch <name>

• Synchronisation du Fork avec son parent $ gh repo sync <owner>/<upstream_name>

Dans notre cas : gh repo sync ch-cbna/GeoNature -b develop

Sources :

• https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork#syncing-a-fork-with-the-github-cli
• https://cli.github.com/manual/gh_repo_sync

Si les modifications du dépôt amont provoquent un conflit, l'interface CLI de GitHub ne peut pas se synchroniser. Vous pouvez définir l'indicateur -force pour écraser la branche de destination. Cependant, il est déconseillé de forcer le merge des deux dépôts, s'il y a conflit, utilisez la méthode avec Git :

a. Changer le répertoire de travail actuel pour votre projet local.

b. Fetch (récupère) les commits respectifs de toutes les branches depuis le dépôt upstream . Les commits de BRANCHNAME seront stockés dans la branche locale upstream/BRANCHNAME. git fetch upstream/BRANCHNAME

c. Vérifier la branche locale par défaut de votre Fork. git checkout BRANCHNAME

d. Fusionner les changements de la branche upstream par défaut dans votre branche locale par défaut. Cela permet de synchroniser la branche par défaut de votre fork avec le dépôt upstream, sans perdre vos modifications locales. git merge upstream/BRANCHNAME

Source : https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

Vous pouvez créer une pull request pour proposer les modifications que vous avez apportées, à un fork d'un dépôt upstream. Dans notre cas, les modifications apportées en local seront envoyées pour discussion /révision/acceptation dans le dépôt Geonature.

• Sur Github : https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork

• Avec Github CLI (en ligne de commande) : https://cli.github.com/manual/gh_pr_create

sudo apt update && sudo apt upgrade sudo apt-get install postgresql postgresql-contrib

PostgreSQL est un serveur qui permet de se connecter à différentes bases de données. Par défaut, seul l'utilisateur postgres peut se connecter.

Toutes les opérations d'administration se font, au départ, avec l'utilisateur postgres. À la fin de l'installation, celui-ci ne possède pas de mot de passe. La première chose à faire sera de créer un nouvel utilisateur, mais pour ce faire, il faut se connecter au moins une fois en tant qu'utilisateur postgres.

• Pour devenir postgres et créer un nouveau role, utiliser sudo : sudo -i -u postgres psql -c "CREATE ROLE <utilisateur> WITH LOGIN PASSWORD '<mot-de-passe>';" <utilisateur> & <mot-de-passe> = choarau
• Modifier les droits du nouvel utilisateur : sudo -i -u postgres psql -c "ALTER USER <utilisateur> WITH SUPERUSER CREATEDB CREATEROLE REPLICATION;"
• Depuis son propre compte, il sera maintenant être possible de créer une base de données portant le nom de l'utilisateur : createdb -E UTF8 -O choarau choarau
• Pour lancer l'invite de commande SQL de PostgreSQL : psql

• Pour héberger la BDD Geonature, il faut créer un nouvel utilisateur : CREATE ROLE geonatadmin WITH LOGIN PASSWORD 'geonatadmin';
• Vérifier les utilisateurs (rôles) de PostgreSQL : \du

\q permettra, à la fin de cette session d'administration dans PostgreSQL, de reprendre la main en tant qu'utilisateur du système.

• Dans le Shell PostgreSQL : CREATE DATABASE gn2_default;

• Vérifier que la BDD a bien été créée : \l

• Se connecter à la BDD gn2_default : \c gn2_default

• Vérifier qu'on est bien connecté à cette base : SELECT current_database();

• Télécharger PostGIS sudo apt update sudo apt install postgis

• Activer PostGIS (v3+) sur la BDD créée psql <my-database-name> -c "CREATE EXTENSION IF NOT EXISTS postgis; CREATE EXTENSION IF NOT EXISTS postgis_raster";

• Vérifier que les extensions PostGIS sont bien installées sur gn2_default : psql \c gn2_default \dx

psql -c "GRANT ALL PRIVILEGES ON DATABASE gn2_default TO geonatadmin;"

Cette étape est nécessaire uniquement quand on a un disque "dur" supplémentaire monté sur /data par exemple. https://wiki-intranet.cbn-alpin.fr/informatique/aides/postgresql#deplacer_le_dossier_des_donnees_data_dir

Documentation Taxhub

• Se placer à l'emplacement du dépôt local souhaité : cd ~/workspace/geonature/web/

• Récupérer la clé SSH du dépôt distant et effectué la commande suivante : git clone [email protected]:PnX-SI/TaxHub.git taxhub

• Se placer dans le dossier taxhub cd ~/workspace/geonature/web/taxhub/

• Basculer sur la branche Develop en local git switch develop

• Récupérer la branche Develop du dépôt distant dans le dépôt local git pull

• Se déplacer sur la branche qu'on est en train de développer git switch feat/meshes

• Combiner la branche distante sur la branche locale git merge develop

• A la racine : Copier/Coller les fichiers settings.ini.sample
• Dans apptax : Copier/Coller les fichiers config.py.sample
• Editer ces fichiers :

settings.ini.sample

mode= dev
db_name= gn2_default
user_pg= geonatadmin
user_pg_pass=geonatadmin

config.py.sample

SQLALCHEMY_DATABASE_URI = "postgresql://geonatadmin:geonatadmin@localhost/gn2_default"
SECRET_KEY = 'super secret key'

Pour générer une clé secrète (32 caractères) : uuidgen

• Les enregistrer-sous en enlevant le ".sample" : config.py & settings.ini

• Installer les dépendances de Geonature sudo apt install unzip python3-venv libgdal-dev libffi-dev libpangocairo-1.0-0

  !!PB!! avec libcharls-dev : sudo apt-get install --reinstall libpq-dev

• Se placer dans le dossier Taxhub cd taxhub/

• Lancer le fichier d’installation et de configuration de l’application git switch develop git pull Pour s'assurer que taxhub est bien à jour avec le dépôt distant git submodule init Pour initialiser les sous-modules (dossier Dependencies) git submodule update ./install_app.sh Si bug au niveau de l'installation de virtual env, enlever et recréer : rm -rf venv & python3 -m venv venv

cd ~/workspace/geonature/web/taxhub source venv/bin/activate flask run

Documentation UsersHub

• Se placer à l'emplacement du dépôt local souhaité : cd ~/workspace/geonature/web/

• Récupérer la clé SSH du dépôt distant et effectué la commande suivante : git clone [email protected]:PnX-SI/UsersHub.git usershub

• Dans le dossier config : Copier/Coller les fichiers config.py.sample & settings.ini.sample
• Editer ces fichiers :

config.py.sample

SQLALCHEMY_DATABASE_URI = "postgresql://geonatadmin:geonatadmin@localhost/gn2_default"
SECRET_KEY = 'super secret key'

Pour générer une clé secrète (32 caractères) : uuidgen

settings.ini.sample

# set to dev to install usershub in development mode
mode=dev
db_name= gn2_default
user_pg= geonatadmin
user_pg_pass=geonatadmin
url_application=127.0.0.1:5001

• Les enregistrer-sous en enlevant le ".sample" : config.py & settings.ini

Lancer le fichier d’installation et de configuration de l’application cd ~/workspace/geonature/web/usershub git switch develop git pull git submodule init git submodule update ./install_app.sh

cd ~/workspace/geonature/web/usershub source venv/bin/activate flask run

• Dans le dossier Config : Copier/Coller les fichiers geonature_config.toml.sample & settings.ini.sample

• Editer ces fichiers pour changer le nom d'utilisateur PostgreSQL et le nom de la BDD et créer un Secret Key:

geonature_config.toml.sample

SQLALCHEMY_DATABASE_URI = "postgresql://geonatadmin:geonatadmin@localhost:5432/gn2_default"
URL_APPLICATION = "http://127.0.0.1:4200"
API_ENDPOINT = "http://127.0.0.1:8000"
API_TAXHUB = "http://127.0.0.1:5000/api"
SECRET_KEY = 'super secret key'

# Nom de l'application dans la page d'accueil.
appName = "DEV - Meshes"

[ALEMBIC]
VERSION_LOCATIONS = "/home/choarau/workspace/geonature/web/usershub/app/migrations/versions/"

Pour générer une clé secrète (32 caractères) : uuidgen

settings.ini.sample

MODE=dev
my_url=http://127.0.0.1:4200/
# Drop eventual existing database during installation
drop_apps_db=true --> ATTENTION ! une fois Geonature installé, repasser en false !
db_name=gn2_default
user_pg=geonatadmin
user_pg_pass=geonatadmin
# Install default French DEM (Mainland France only - BD alti 250m)) 
install_default_dem=false --> 1 heure de chargement si true
add_sample_data=false --> pour insérer données sinp paca
# Installer le module validation
install_module_validation=false
# Installer le module Occurrence d'habitat
install_module_occhab=false
usershub_release=develop
taxhub_release=develop

• Les enregistrer-sous en enlevant le ".sample" : geonature_config.toml & settings.ini

• Se déconnecter de la base de données dans DBeaver par exemple.
• Se rendre dans le dossier /install cd install/ git submodule init && git submodule update

Backend

./01_install_backend.sh --dev

BDD

./03_create_db.sh

Frontend

./05_install_frontend.sh --dev

Ouvrir 4 consoles :

• GeoNature cd ~/workspace/geonature/web/geonature/frontend npm run start

• TaxHub cd ~/workspace/geonature/web/taxhub flask run --port=5000

• UsersHub cd ~/workspace/geonature/web/usershub flask run --port=5001

• Backend GeoNature cd ~/workspace/geonature/web/geonature/backend source venv/bin/activate geonature dev-back

• Backend : Python + Webservices + BDD

• Frontend : Angular (Gunicorn en Production / Flask en Developpement)

Gunicorn Gunicorn est un WSGI (Web Server Gateway Interface). WSGI est une norme qui sert à définir comment un serveur Python et son application peuvent discuter.

source : https://faun.pub/deploy-flask-app-with-nginx-using-gunicorn-7fda4f50066a

Service systemd La commande systemctl est utilisée en Production (commande Gunicorn) pour lancer les applications Geonature. Pour l'utiliser, il faut se placer dans le dossier /etc/systemd/system. Ce fichier contient les fichiers de service des applications Geonature (Taxhub, UsersHub, Geonature). Pour lancer ces applications en mode Production : sudo systemctl {start,stop} geonature

Alembic Outil de versionnement de BDD à utiliser avec la boîte à outils de base de données SQLAlchemy pour Python. Documentation Alembic Un uid pour chaque banche. Chaque uid correspond à un fichier python où est indiqué la version précédente de la BDD utilisée + ses dépendances. stamp = tampon de version geonature db stamp --> voir quelle version de la BDD geonature db auto-upgrade --> met à jour jusqu'à la dernière version geonature db downgrade --> revient à la version d'avant geonature db upgrade@head --> met à jour jusqu'à telle version

Les versions de la BDD sont stockées dans le dossier /geonature/migrations/version et dans le schema Public geonature db status --> connaître la version actuelle de la BDD

SQLAlchemy

pg_activity Permet d esuivre l'activité de la BDD depuis le Terminal

sudo -u postgres pg_activity -U postgres
vi ~/.bash_aliases
alias pga='sudo -u postgres pg_activity -U postgres'
pga

Scripts de Jean-Pascal : https://github.com/jpm-cbna/various-scripts/tree/main/geonature

various-scripts/geonature/copy-partial/copy_partial_data_between_gn_db.sh

pg_admin_name="choarau"
src_db_name="gn2_default_sinppaca"
dest_db_name="gn2_default"
area_code="05004"