docs: mise à jour de la doc ETL (#530)

DNUM-SocialGouv · Jul 29, 2024 · adc2f9a · adc2f9a
1 parent 8666d92
commit adc2f9a
Show file tree

Hide file tree

Showing 21 changed files with 248 additions and 108 deletions.
diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md
@@ -5,13 +5,19 @@ sidebar_position: 1
 
 # Architecture de l'ETL
 
-_10 Mars 2023_
+_10 Mars 2023 (mis à jour le 24 Juillet 2024)_
+
+## Architecture globale
+![1j1s-etl-global](./assets/1j1s-etl-schema.png)
 
 ## Introduction
 
+:::info Contexte
 Ce projet a été réalisé en suivant au mieux les principes du [Domain-Driven Design](https://alexsoyes.com/ddd-domain-driven-design/).
+:::
 C'est pourquoi nous avons identifié des contextes métier indépendants les uns des autres comme représentés ci-dessous :
 
+
 **Au 10/03/2023 :**
 
 ![architecture-etl](./assets/big-picture-etl.png)

diff --git a/docs/docs/assets/1j1s-MiseEnProduction-github.png b/docs/docs/assets/1j1s-MiseEnProduction-github.png
diff --git a/docs/docs/assets/1j1s-MiseEnProduction.png b/docs/docs/assets/1j1s-MiseEnProduction.png
diff --git a/docs/docs/assets/1j1s-cron.png b/docs/docs/assets/1j1s-cron.png
diff --git a/docs/docs/assets/1j1s-etl-schema.png b/docs/docs/assets/1j1s-etl-schema.png
diff --git a/docs/docs/assets/1j1s-git-convention.png b/docs/docs/assets/1j1s-git-convention.png
diff --git a/docs/docs/assets/1j1s-minio.png b/docs/docs/assets/1j1s-minio.png
diff --git a/docs/docs/conventions/git.md b/docs/docs/conventions/git.md
@@ -12,6 +12,7 @@ _20 Avril 2023_
 ### Convention
 
 Nous allons nous baser sur la convention "[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)".
+![1J1S git convention](../assets/1j1s-git-convention.png)
 
 ### Langue
 

diff --git a/docs/docs/tuto/consulter-contenu-minio.md b/docs/docs/tuto/consulter-contenu-minio.md
@@ -5,10 +5,13 @@ sidebar_position: 3
 
 # Comment consulter le contenu du dépôt MinIO
 
-_20 Avril 2023_
+_20 Avril 2023 (mis à jour le 24 Juillet 2024)_
 
+:::info Contexte
 Nous utilisons l'interface `Amazon Web Services Command Line Interface (CLI)` afin de pouvoir consulter
 le contenu du dépôt de fichier MinIO que nous utilisons sur le projet.
+:::
+![MinIO](../assets/1j1s-minio.png)
 
 ## Installation
 

diff --git a/docs/docs/tuto/copie-donnee-en-local.md b/docs/docs/tuto/copie-donnee-en-local.md
@@ -0,0 +1,108 @@
+---
+sidebar_label: Que faire si l'indexation des données reste bloquée à 10000 données ?
+sidebar_position: 7
+---
+
+
+# Lorsque l'indexation depuis Strapi échoue : copier les données en local
+
+
+
+_23 Juillet 2024_
+
+:::info Contexte
+Si vous avez suivi la procédure de resynchronisation et qu'à l'appui sur "update" la valeur du nombre de données indexée reste bloquée à 10000 : L'anomalie provient du plugin Meilisearch utilisé qui limite à 10000 indexations. 
+Lorsque l’ETL effectue son travail d’upsert des contenus à charger sur Strapi, celui-ci impacte le nombre d'éléments d’une collection (offre de stage, annonces de logements…) et modifie nombre d’entre eux. Puis, le plugin Meilisearch, au travers d’une réaction à un évènement propagé par Strapi, envoie un document à indexer dans Meilisearch.
+:::
+
+
+### Explication de la procédure
+Une désynchronisation entre le contenu indexé par Meilisearch et le contenu présent en base de données est donc quotidiennement présente.
+Pour résoudre le problème nous avons mis en place une solution de contournement en lançant l'indexation depuis un strapi local, connecté à la base de recette.
+
+---
+
+## Copie des données de recette en local
+
+
+Le script `populate-with-recette-data.sh` à la racine a été mis en place pour la copie des données du CMS de recette vers le CMS conteneurisé.
+Ci-dessous l'explication du fonctionnement de ce script. 
+
+### Prérequis
+
+Afin de pouvoir exécuter le script, il faut avoir copié le contenu de `.env.docker' dans '.env'.
+
+Ensuite, vous devez avoir en votre possession une clef vous permettant de vous connecter sur l'environnement depuis lequel l'on veut copier.
+Pour la générer : il suffit de se connecter sur son compte Scalingo et générer un API Token. 
+
+
+Cette clef (API Token) est à remplir dans la variable d'environnement `SCALINGO_API_TOKEN` dans `.env`.
+
+Pour manipuler les conteneurs et applications sur Scalingo, il vous faudra [installer leur CLI](https://doc.scalingo.com/platform/cli/start#install-scalingo-cli)
+
+Vous pouvez exécuter la commande suivante pour installer ou mettre à jour `Scalingo CLI`:
+
+```/bin/bash
+$ curl -O https://cli-dl.scalingo.com/install && bash install
+```
+
+### Variables d'environnement utiles
+
+```/bin/bash
+# populate-with-recette-data.sh
+
+export SCALINGO_APP='1j1s-main-cms'
+export SCALINGO_REGION='osc-fr1'
+export ADDON_NAME='postgresql'
+export SCALINGO_DB_USER='<l'utilisateur db prod>'
+```
+
+```/bin/bash
+# .env
+
+SCALINGO_API_TOKEN='<la clef API de Scalingo>'
+```
+
+### Connexion
+
+Dans un premier temps, il faut se connecter avec la clef récupérée ci-dessus.
+Une vérification est faite en amont pour arrêter le script s'il n'y a pas de `.env` local.
+
+```/bin/bash
+if [ -f .env ]
+then
+  export $(cat .env | xargs)
+else
+  exit 1
+fi
+
+scalingo login --api-token ${API_TOKEN}
+```
+
+### Téléchargement de la Backup
+
+Pour télécharger la dernière backup de la BDD en recette, on lance les commandes suivantes :
+
+```/bin/bash
+addon_id=$(scalingo addons | grep $ADDON_NAME | cut -d'|' -f3 | tr -d ' ')
+mkdir -p tmp && cd tmp
+scalingo --addon ${addon_id} backups-download --output ./backup
+tar -xvf ./backup
+for filename in *.pgsql; do eval mv \"$filename\" \"backup.pgsql\"; done
+cd ..
+```
+
+A ce stade, nous avons un fichier `backup.psql` dans le dossier `tmp` qui contient la BDD de recette.  
+
+### Monter la backup dans le conteneur local
+
+Une fois le téléchargement terminé, il suffit de lancer le docker de BDD en lui chargeant le fichier.
+
+```/bin/bash
+docker compose down -v
+docker compose --env-file .env.docker up -d db
+sleep 5
+docker compose exec db psql "${DATABASE_URL}" -c "CREATE USER ${SCALINGO_DB_USER} SUPERUSER;"
+docker compose cp ./tmp/backup.pgsql db:/tmp/backup.pgsql
+docker compose exec db pg_restore -d ${DATABASE_URL} /tmp/backup.pgsql
+```
diff --git a/docs/docs/tuto/creer-nouveau-bucket-minio.md b/docs/docs/tuto/creer-nouveau-bucket-minio.md
@@ -1,15 +1,18 @@
 ---
 sidebar_label: Comment créer un nouveau bucket sur Minio
-sidebar_position: 7
+sidebar_position: 4
 ---
 
 # Comment créer un nouveau bucket sur Minio
 
-_01 Août 2023_
+_01 Août 2023 (mis à jour le 24 Juillet 2024)_
 
-
-## Contexte
+:::info Contexte
 Lors de la création d'une nouvelle étape d'Extract / Transform / Load, il faut créer les buckets correspondants sur Minio qui accueilleront les fichiers correspondants.
+:::
+
+
+## Cas d'usage
 
 Exemple pour les différentes étapes d'ETL des annonces de logements, je dois créer les buckets suivants : 
 ```

diff --git a/docs/docs/tuto/le_flux_ne_met_plus_a_jour.md b/docs/docs/tuto/le_flux_ne_met_plus_a_jour.md
@@ -5,10 +5,12 @@ sidebar_position: 5
 
 # Lorsque le flux ne se mets plus à jour
 
-_20 Avril 2023_
+_20 Avril 2023 (mis à jour le 24 Juillet 2024)_
 
-## Détail de l’erreur
+:::info Contexte
 Le flux ne se met plus à jour sur Strapi ou plusieurs offres sont toujours disponibles pour le flux mais ces dernières sont peut être obsolètes.
+:::
+
 
 ## Analyse de l’erreur
 Vérifier si les tâches crons fonctionnent : 

diff --git a/docs/docs/tuto/purge-des-donnees.md b/docs/docs/tuto/purge-des-donnees.md
@@ -5,27 +5,27 @@ sidebar_position: 2
 
 # Purge des données
 
-_20 Avril 2023_
+_20 Avril 2023 (mis à jour le 24 Juillet 2024)_
 
-## Contexte d'utilisation
+:::info Contexte
+Des données sont corrompues et que l'origine est introuvable, il convient peut être d'effectuer une purge des données.
+:::
 
-- Lorsque des données sont corrompues et que l'origine est introuvable. 
+:::danger Pré-requis
+Avoir un token permettant l'accèes à l'application sur scalingo
+:::
 
-## Prérequis
+## Procédure de purge
 
- * Avoir un token permettant l'accèes à l'application sur scalingo
-
-## Conseils
-
-### Variables d'environnements
+### Vérifier les variables d'environnements
 
 ```env
 
 SCALINGO_APP=${APP_NAME}
 
 ```
 
-## Commande à lancer
+### Commandes à exécuter
 
 Vous avez la possibilité de supprimer l'ensemble des données des contextes suivants :
 

diff --git a/docs/docs/tuto/resynchronisation-meilisearch-strapi.md b/docs/docs/tuto/resynchronisation-meilisearch-strapi.md
diff --git a/docs/docs/tuto/rollback-database.md b/docs/docs/tuto/rollback-database.md
@@ -5,7 +5,12 @@ sidebar_position: 1
 
 # Rollback de base de données
 
-_20 Avril 2023_
+_20 Avril 2023 (mis à jour le 24 Juillet 2024)_
+
+:::info Contexte
+Il est parfois nécessaire, pour annuler des transactions incorrectes ou non désirées, restaurer l'intégrité des données et garantir la cohérence du système après une erreur ou une défaillance de réaliser un rollback de la base de donnée. 
+:::
+
 
 ## Accéder au dashboard de la base de données
 
@@ -15,7 +20,7 @@ c'est déjà fait pour les environnements de production).
 Maintenant, vous allez peut-être vouloir créer une back-up manuellement. Pour ce faire, il faut se rendre sur Scalingo, 
 là où les ressources d'une application sont détaillées :
 
-![img](../assets/onglet-scalingo-app.png)
+![1j1s-scalingo](../assets/onglet-scalingo-app.png)
 
 Ensuite, cliquez sur le bouton `Go to dashboard` à côté de l'addon correspondant à votre base de données. Cela va ouvrir
  une fenêtre avec le dashboard correspondant à votre base de données.
@@ -26,11 +31,11 @@ Ensuite, cliquez sur le bouton `Go to dashboard` à côté de l'addon correspond
 
 Maintenant, vous avez le dashboard ci-dessous devant les yeux :
 
-![img](../assets/dashboard-bdd.png)
+![1j1s-bdd](../assets/dashboard-bdd.png)
 
 Rendez vous sur l'onglet `Backups`, en haut à droite :
 
-![img](../assets/backups.png)
+![1j1s-backup](../assets/backups.png)
 
 Pour créer votre backup, il vous suffit maintenant d'appuyer sur le bouton `Make manual backup`. Vous le verrez 
 apparaître dans la liste des backups disponibles sur la droite de l'interface. Téléchargez cette sauvegarde via le 

diff --git a/docs/docs/tuto/scheduled-tasks.md b/docs/docs/tuto/scheduled-tasks.md
@@ -1,11 +1,16 @@
 ---
 sidebar_label: Les Scheduled tasks, comment ça marche ?
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Utiliser les Scheduled Tasks Scalingo
 
-_20 Avril 2023_
+_20 Avril 2023 (mis à jour le 24 Juillet 2024)_
+
+:::info Contexte
+Une scheduled task (ou tâche planifiée) est une opération programmée pour s'exécuter automatiquement à des moments prédéfinis ou selon des intervalles spécifiques. Par exemple transférer les données du CEJ vers vers un serveur externe.
+:::
+![1j1s-cron](../assets/1j1s-cron.png)
 
 ## Démarrage
 

diff --git a/docs/docs/tuto/sos.md b/docs/docs/tuto/sos.md
@@ -5,11 +5,12 @@ sidebar_position: 0
 
 # Que faire si tout se passe mal après une mise en production ?
 
-_20 Avril 2023_
-
+_20 Avril 2023 (mis à jour le 24 Juillet 2024)_
 
+:::info Contexte
 Si demain, vous êtes amenés à faire une mise en production et que d'avance ça devait mal se passer, pas de panique ! 
 Ce ne sera qu'une nouvelle mise en production de ratée dans la longue et triste histoire des mises en production ratées.
+:::
 
 ## Pense-bête
 

diff --git a/docs/docs/tuto/tutoMeP.md b/docs/docs/tuto/tutoMeP.md
@@ -0,0 +1,48 @@
+---
+sidebar_label: Comment mettre en Production ?
+sidebar_position: 1000
+---
+
+
+# Comment mettre en production ?
+
+
+
+_12 Juillet 2024 (mis à jour le 24 Juillet 2024)_
+
+:::info Contexte
+Terraform est un outil d'Infrastructure as Code (IaC) développé par HashiCorp qui permet de définir, provisionner et gérer des infrastructures de manière déclarative. Associé aux github actions, il nous permet de pousser automatiquement du code en Production. 
+:::
+
+
+## Fonctionnement
+
+En définissant l'infrastructure comme du code, il permet une gestion plus efficace, traçable et reproductible des environnements de production, tout en s'intégrant parfaitement dans les pipelines CI/CD pour un déploiement continu et fiable.
+
+![Tuto Mise En Production](../assets/1j1s-MiseEnProduction.png)
+
+Les avantages sont multiples : 
+* **Traçabilité** : Chaque modification de l'infrastructure est versionnée et traçable via des systèmes de gestion de code source comme Git.
+- **Reproductibilité** : Les mêmes configurations peuvent être utilisées pour déployer des environnements identiques, facilitant les tests et la production.
+- **Multi-cloud** : Terraform supporte plusieurs fournisseurs de cloud (AWS, Azure, GCP, etc.), permettant une gestion cohérente des infrastructures sur différentes plateformes.
+- **Déclaratif** : La nature déclarative de Terraform simplifie la gestion des infrastructures complexes en se concentrant sur l'état final souhaité plutôt que sur les étapes nécessaires pour y parvenir.
+
+## Mise en oeuvre via Github
+
+Les actions ci-dessous sont à réaliser pour chaque projet présent sur Github : 
+* 1j1s-front
+* 1j1s-etl
+* 1j1s-main-cms
+
+Les différentes actions à réaliser pour le <code>1j1s-etl</code> :
+
+* Sélectionner le projet à publier
+* Sélectionner "Actions"
+* Sélectionner "Mise en production"
+* Sélectionner "Run workflow"
+* Valider le lancement de la mise en production via le CTA "Run workflow"
+
+![Tuto Mise En Production via GitHub](../assets/1j1s-MiseEnProduction-github.png)
+* Envoyer un message sur le MM "MEP" indiquant qu'une mise en production est en cours
+* S'assurer qu'aucune erreur n'est remontée 
+* Mettre à jour le message sur le MM "MEP" afin d'indiquer que la mise en production est terminée