📚 Réorganisation de la doc : réunoin de tutoriels et comment faire (#1785)

Author: fabienheureux

docs/comment-faire/README.md

@@ -1,15 +1,13 @@
 # 🤔 COMMENT FAIRE
 
-
 ```{toctree}
 :hidden:
 
 troubleshooting.md
-data/deployment.md
+deployment.md
 data/config-dev-env.md
 django/commandes.md
 django/update-ext-id.md
-deployment/deployment.md
 development/development.md
 prod/commandes.md
 prod/rollback.md

docs/comment-faire/_medias/troubleshooting-1.png

@@ -0,0 +1,115 @@
+# DevOps, déploiement, opérations
+
+## Déploiement de la plateforme Airflow hors CD
+
+La plateforme Data est déploié automatiquement par le processus de `Continuous Deployment`. Cependant, il est possibel d'avoir besoin de « forcer » un déploiement.
+
+### Procédure de déploiement
+
+#### Prérequis
+
+- configururer sa clé ssh dans l'interface de clevercloud (cf. doc clevercloud)
+- configurer un "remote repository" pour `airflow-webserver` pour ce repository et pour chaque environnemnt
+- configurer un "remote repository" pour `airflow-scheduler` pour ce repository et pour chaque environnemnt
+- pousser le code souhaité sur la branch master des 2 repository
+
+#### en PREPROD
+
+```sh
+git remote add preprod-airflow-scheduler git+ssh://git@push-n3-par-clevercloud-customers.services.clever-cloud.com/app_3d1f7d89-d7f0-433a-ac01-c663d4729143.git
+git remote add preprod-airflow-webserver git+ssh://git@push-n3-par-clevercloud-customers.services.clever-cloud.com/app_d3c229bf-be85-4dbd-aca2-c8df1c6166de.git
+git push preprod-airflow-scheduler mabranch:master
+git push preprod-airflow-webserver mabranch:master
+```
+
+#### en PROD
+
+```sh
+git remote add prod-airflow-scheduler git+ssh://git@push-n3-par-clevercloud-customers.services.clever-cloud.com/app_fda5d606-44d9-485f-a1b4-1f7007bc3bec.git
+git remote add prod-airflow-webserver git+ssh://git@push-n3-par-clevercloud-customers.services.clever-cloud.com/app_efd2802a-1773-48e0-987e-7a6dffb929d1.git
+git push prod-airflow-scheduler mabranch:master
+git push prod-airflow-webserver mabranch:master
+```
+
+## Déploiement sur Scalingo
+
+Nous avons besoin d'installer GDAL comme c'est expliqué dans la doc suivante : [https://techilearned.com/configure-geodjango-in-scalingo/](https://techilearned.com/configure-geodjango-in-scalingo/) cf. [https://doc.scalingo.com/platform/app/app-with-gdal](https://doc.scalingo.com/platform/app/app-with-gdal)
+
+le code est déployé en preprod lors de la mise à jour de la branche main
+
+et en production quand il est tagué avec en respectant le format de version semantique vX.Y.Z
+
+### Déploiement du code de l'interface
+
+le code de l'interface est déployé sur le repo git de scalingo à conditions que les tests soit passés avec succès via Github
+
+## Déploiement sur CleverCloud
+
+<!-- TODO data plateforme -->
+
+## Deploiment sur Scaleway
+
+<!-- TODO s3 et bientôt plus ? -->
+
+## Accéder à un shell en production
+
+Pour executer une commande en production, il faut au préalable se connection au shell via le CLI Scalingo.
+
+- [Installer le CLI](https://doc.scalingo.com/platform/cli/start)
+
+Ensuite il est possible d'ouvrir un shell (ici bash) dans le worker Scalingo.
+
+```sh
+scalingo run --app quefairedemesobjets bash
+```
+
+L'intégralité des commandes possibles n'est pas documentée ici, elle l'est dans la [documentation officielle de Django](https://docs.djangoproject.com/en/dev/ref/django-admin/#django-admin-and-manage-py)
+
+L'ensemble des commandes documentées ci-après peut être lancée soit depuis un environnement local, soit depuis un shell en production ou pré-production.
+
+## Rollback: Revenir à une version précédente de l'application déployée
+
+Dans le cas d'une catastrophe en production, il est parfois nécessaire de revenir à la version précédente.
+Suivez les étapes ci-dessous pour revenir à la version précédente
+
+### Rollback des interfaces
+
+#### Prérequis
+
+- Prévenir l'équipe du problème de prod et du rollback à venir sur Mattermost
+- Voir avec l'administrateur des données (Christian) si des modifications récentes sont à sauvegarder avant la restauration de la base de données
+- Tester la procédure de rollback ci-dessous en preprod avant de l'appliquer en production
+
+#### Rollback du code
+
+- Vérifier le tag de version précédente sur la [page des releases github](https://github.com/incubateur-ademe/quefairedemesobjets/releases)
+- Pousser le tag de la version précédente en production
+
+```sh
+git remote add prod-interface git@ssh.osc-fr1.scalingo.com:quefairedemesobjets.git
+git push -f prod-interface <TAG>:master
+```
+
+#### Base de données
+
+Restaurer la base de données avec la sauvegarde souhaitée (géréralement, la sauvegarde juste avant l'incident)
+
+- Copier de la sauvegarde de la base de données localement à partir de l'[interface Scalingo](https://dashboard.scalingo.com/apps/osc-fr1/quefairedemesobjets/db/postgresql/backups/list)
+- Déclarer les variables d'environnements ci-dessous et éxécuter la commande de restauration
+
+```sh
+DUMP_FILE=20241216001128_quefairedem_5084.tar.gz
+DATABASE_URL=<Copie from scalingo env variable SCALINGO_POSTGRESQL_URL>
+for table in $(psql "${DATABASE_URL}" -t -c "SELECT \"tablename\" FROM pg_tables WHERE schemaname='public'"); do
+     psql "${DATABASE_URL}" -c "DROP TABLE IF EXISTS \"${table}\" CASCADE;"
+done
+pg_restore -d "${DATABASE_URL}" --clean --no-acl --no-owner --no-privileges "${DUMP_FILE}"
+```
+
+_TODO: refaire un script de restauration de la base de données plus simple à utiliser avec des input et tout et tout_
+
+#### Vérifier que la restauration est effective
+
+Accéder à la carte et jouer avec : [La carte](https://lvao.ademe.fr/carte)
+Accéder au formulaire et joue avec : [Le formulaire](https://lvao.ademe.fr/formulaire)
+Accéder à l'administration Django et vérifier les données qui ont été restaurée : [Admin](https://lvao.ademe.fr/admin)

docs/comment-faire/data/config-dev-env.md

@@ -1,4 +1,4 @@
-# Development
+# Développemnt local
 
 ## Environnement de développement
 
@@ -177,3 +177,25 @@ done
 pg_restore -d "${DATABASE_URL}" --clean --no-acl --no-owner --no-privileges "${DUMP_FILE}"
 ```
 
+## Configurer la plateforme DATA en environnement de développement
+
+Copier les variable d'environnement dags/.env.template vers dags/.env
+
+```sh
+cp dags/.env.template dags/.env
+```
+
+Lancer les containers docker avec docker compose:
+
+```sh
+docker compose --profile airflow up
+```
+
+docker compose lancera :
+
+- la base de données postgres nécessaire à la webapp de la carte
+- la base de données postgres nécessaire à Airflow
+- un webserver airflow
+- un scheduler airflow en mode LocalExecutor
+
+accéder à l'interface d'Airflow en local [http://localhost:8080](http://localhost:8080) ; identifiant/mot de passe : airflow / airflow

docs/comment-faire/data/deployment.md

@@ -1,7 +1,7 @@
 # Utiliser les fixtures
 
 Le projet utilise des fixtures Django[^1] pour les tests.
-Celles-ci sont basées sur de la donnée issue de la base de production afin  de tester l'application sur des situations _de la vraie vie_.
+Celles-ci sont basées sur de la donnée issue de la base de production afin de tester l'application sur des situations _de la vraie vie_.
 
 ## Générer des fixtures, cas général
 
@@ -22,17 +22,20 @@ Le volume de données de la table des Acteurs étant gigantesque, les fixtures d
 
 Pour ce faire, sont listées dans le `Makefile` une liste de `pk` d'acteurs (champ `identifiant_unique`).
 Ces identifiants ont été récupérés à la main, depuis le frontend de la carte :
+
 1. Faire une recherche pour la zone souhaitée
 2. Récupérer le lien de l'acteur dans la fiche détaillée (en cliquant sur le lien de partage par exemple) --> https://lvao.ademe.fr/adresse_details/3kQK86DEWA3ZrcirdzzBez l'id est 3kQK86DEWA3ZrcirdzzBez
 3. Chercher cet id dans l'admin Django : https://lvao.ademe.fr/admin/qfdmo/displayedacteur/?q=eYKxBYDMDoMXTr8iiw69Ek
 4. Récupérer le champ `identifiant_unique` : il peut être un uuid ou un assemblage de chaînes de caractères mentionnant la source, par exemple `ocad3e_SGS-02069`
 5. Ajouter cet identifiant dans le `Makefile` à la suite des autres, derrière le flag `--pk` dans la commande `generate-fixtures-acteurs`
 
 6. Une fois cela fait, il faut récupérer les _primary key_ des propositions de service associées.
-Cela peut-être fait depuis le shell `django` :
+   Cela peut-être fait depuis le shell `django` :
+
 ```sh
 make shell
 ```
+
 ```py
 # 1. importer le modèle Django
 from qfdmo.models import DisplayedActeur
@@ -45,8 +48,10 @@ list(DisplayedActeur.objects.filter(pk__in=pks).values_list("proposition_service
 
 # Sortie attendue: [2163243, 2163244, 2163245, 243160, 435885, 1699381, 738371, 738372, 719100]
 ```
+
 7. Cette liste de `pk` peut alors être collées dans le `Makefile`
 8. Les fixtures peuvent être re-générées
+
 ```sh
 make generate-fixtures-acteurs
 
@@ -59,6 +64,7 @@ git commit -m "mise à jour des fixtures"
 ## Utiliser les fixtures
 
 Les fixtures peuvent être utilisées de plusieurs manières :
+
 - Dans les tests
 - En local
 - Dans la CI
@@ -72,6 +78,7 @@ make db-restore-for-tests
 ```
 
 Dans les tests, les fixtures peuvent être importées en utilisant la fonction `callcommand` de Django :
+
 ```py
 from django.core.management import call_command
 call_command('loaddata', 'synonymes', 'produits')
@@ -80,6 +87,4 @@ call_command('loaddata', 'synonymes', 'produits')
 Le nom des fixtures à utiliser est celui du nom du fichier `.json` de la fixture.
 Django se charge de découvrir automatiquement la fixture correspondante.
 
-
-
 [^1]: [https://docs.djangoproject.com/en/5.2/topics/db/fixtures/](https://docs.djangoproject.com/en/5.2/topics/db/fixtures/)

docs/comment-faire/deployment.md

@@ -49,9 +49,9 @@ pg_restore -d 'postgres://<user>:<password>@<host>:<port>/<database>?sslmode=req
 
 Pour chacune des instances de l'environnement, aller mettre à jour les variables d'environnement et redémarrer les instances:
 
-* webapp quefairedemesobjets
-* airflow-webserver
-* airflow-scheduler
-* metabase
+- webapp quefairedemesobjets
+- airflow-webserver
+- airflow-scheduler
+- metabase
 
 Tester et constater que la nouvelle base de données est utilsée