diff --git a/docs/docs/architecture.md b/docs/docs/architecture.md index 79c8387e..24ba4781 100644 --- 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 new file mode 100644 index 00000000..9fbc792d Binary files /dev/null and b/docs/docs/assets/1j1s-MiseEnProduction-github.png differ diff --git a/docs/docs/assets/1j1s-MiseEnProduction.png b/docs/docs/assets/1j1s-MiseEnProduction.png new file mode 100644 index 00000000..2f6a00f0 Binary files /dev/null and b/docs/docs/assets/1j1s-MiseEnProduction.png differ diff --git a/docs/docs/assets/1j1s-cron.png b/docs/docs/assets/1j1s-cron.png new file mode 100644 index 00000000..6b07b941 Binary files /dev/null and b/docs/docs/assets/1j1s-cron.png differ diff --git a/docs/docs/assets/1j1s-etl-schema.png b/docs/docs/assets/1j1s-etl-schema.png new file mode 100644 index 00000000..65e64200 Binary files /dev/null and b/docs/docs/assets/1j1s-etl-schema.png differ diff --git a/docs/docs/assets/1j1s-git-convention.png b/docs/docs/assets/1j1s-git-convention.png new file mode 100644 index 00000000..09f48b41 Binary files /dev/null and b/docs/docs/assets/1j1s-git-convention.png differ diff --git a/docs/docs/assets/1j1s-minio.png b/docs/docs/assets/1j1s-minio.png new file mode 100644 index 00000000..563e1519 Binary files /dev/null and b/docs/docs/assets/1j1s-minio.png differ diff --git a/docs/docs/conventions/git.md b/docs/docs/conventions/git.md index fe4ae3a6..f430858f 100644 --- 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 index 674094c8..abf49580 100644 --- 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 new file mode 100644 index 00000000..a05fdc88 --- /dev/null +++ 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='' +``` + +```/bin/bash +# .env + +SCALINGO_API_TOKEN='' +``` + +### 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 index 569d50b2..e29d7107 100644 --- 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 index a81ce181..5a468c77 100644 --- 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 index cd2f6094..b2ddafaa 100644 --- a/docs/docs/tuto/purge-des-donnees.md +++ b/docs/docs/tuto/purge-des-donnees.md @@ -5,19 +5,19 @@ 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 @@ -25,7 +25,7 @@ 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 deleted file mode 100644 index 9f2f17ed..00000000 --- a/docs/docs/tuto/resynchronisation-meilisearch-strapi.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -sidebar_label: Comment resynchroniser les données Meilisearch avec celles de Strapi ? -sidebar_position: 6 ---- - -# Resynchroniser les données Meilisearch avec celles de Strapi - -_20 Avril 2023_ - -## Contexte - -Du fait de l'indexation document par document imposée par la stratégie d'insertion, modification et suppression d'une -entrée dans une collection par Strapi, il peut arriver qu'une désynchronisation se produise entre Meilisearch et Strapi. - -## Qu'est-ce qui nous met la puce à l'oreille ? - -En règle générale, nous nous apercevons de cette désynchronisation lorsque nous tentons d'accéder au détail d'une offre -de stage ou d'une annonce de logement et que l'interface utilisateur nous dit que nous n'avons pas trouvé l'offre ou -l'annonce. - -## Que faire ? - -1. Connectez-vous à l'application `Main CMS` de production, si vous ne savez pas où trouver les identifiants, demandez ; -2. Arrivé sur l'interface administrateur, vous trouverez un onglet `Meilisearch` sur le panneau de gauche, cliquez -dessus ; -3. Cherchez ensuite dans la liste des collections celle qui pose soucis ; -4. Si une désynchronisation est en effet d'actualité, vous devriez voir un différentiel entre le nombre de documents -présents en base de données et le nombre d'entrées de la collection dans la base de données de Strapi : - -Exemple sans désynchronisation : - -![ex sans désynchronisation](../assets/synchronisation-ok.png) - -Exemple avec désynchronisation : - -![ex avec désynchronisation](../assets/synchronisation-nok.png) - -5. Vous voyez un bouton `Update`tout à droite de la ligne qui vous permet de purger les documents de ladite collection -sur Meilisearch et de les réindexer par batch, cliquez dessus une fois et soyez patient ; -6. Attendez un moment puis vérifiez si la désynchronisation a disparu. - -## Si ça ne résout pas le problème ? - -Vous pouvez investiguer davantage en manipulant directement l' -[API de Meilisearch](https://docs.meilisearch.com/reference/api/overview.html) pour voir si l'indexation est toujours -en cours ou non, voir si des documents ont bel et bien été envoyés à Meilisearch etc... - -Essayez de durcir les méthodes liées à la transformation de vos données dans l'application `Main CMS` pour voir si cela -résout votre problème. diff --git a/docs/docs/tuto/rollback-database.md b/docs/docs/tuto/rollback-database.md index 497ea86f..4ab893d8 100644 --- 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 index 51ad8e9c..bcc402f7 100644 --- 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 index 47b57155..be35671f 100644 --- 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 new file mode 100644 index 00000000..6e464407 --- /dev/null +++ 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 1j1s-etl : + +* 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 diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 60787214..e709a1a7 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -101,6 +101,18 @@ const config = { href: 'https://dnum-socialgouv.github.io/1j1s-front/docs/architecture', target: '_self', }, + { + "href": "https://dnum-socialgouv.github.io/1j1s-cms/docs/architecture", + "label": "CMS", + "position": "left", + "target": "_self" + }, + { + "label": "Design System", + "position": "left", + "target": "_parent", + "to": "./storybook" + }, { type: 'docsVersionDropdown', position: 'right', diff --git a/docs/pages/index.tsx b/docs/pages/index.tsx index ed26f655..b07338cc 100644 --- a/docs/pages/index.tsx +++ b/docs/pages/index.tsx @@ -17,8 +17,8 @@ function HomepageHeader() {
- Commencer à contribuer - 30min ⏱️ + to="https://www.1jeune1solution.gouv.fr/"> + Aller sur 1Jeune1Solution
diff --git a/docs/src/components/HomepageFeatures/index.tsx b/docs/src/components/HomepageFeatures/index.tsx index a46c575e..7563a832 100644 --- a/docs/src/components/HomepageFeatures/index.tsx +++ b/docs/src/components/HomepageFeatures/index.tsx @@ -10,37 +10,32 @@ type FeatureItem = { const FeatureList: FeatureItem[] = [ { - title: 'Facile d\'utilisation', - Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default, - description: ( - <> - Une documentation complète dans une mise en page moderne et facile d'accès, - voilà les objectifs de la documentation 1jeune1solution.
Avez-vous déjà essayé la recherche ? - - ), - }, - { - title: 'Facile de contribuer', - Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default, - description: ( - <> - Il manque quelque chose ?
- vous avez trouvé une erreur ?
- A vous de le corriger - en proposant un ajout ou un correctif dans le dossier docs du projet. - - ), - }, - { - title: 'Extensible par nature', - Svg: require('@site/static/img/undraw_docusaurus_react.svg').default, - description: ( - <> - Grâce aux plugins, les documentations de tous les dépôts de code source 1jeune1solution - sont réunis, mais en plus les pages sont illustrées et riche de multiples intégrations. - - ), - }, + Svg: require('@site/static/img/undraw_docusaurus_react.svg').default, + description: ( + <> + Toutes les informations à connaitre sur le projet Front permettant d'améliorer l'apparence visuelle et la lisibilité des informations affichées sur 1Jeune1Solution mais également certains éléments comme le tracking ou l'affichage des données en provenance du CMS. + + ), + title: 'Le projet 1J1S-Front', + }, + { + Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default, + description: ( + <> + Toutes les informations à connaitre sur le projet ETL permettant l'extraction, la transformation et le chargement de données provenant de multiples sources telles que les offres de logements étudiant. + + ), + title: 'Le projet 1J1S-ETL', + }, + { + Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default, + description: ( + <> + Toutes les informations à connaitre sur le projet CMS, qui permet la mise en place du système de gestion de contenu à destination des chargés de déploiement. Ils auront la main pour créer, modifier et publier du contenu web tels que les articles ou les services jeunes. + + ), + title: 'Le projet 1J1S-CMS', + }, ]; function Feature({title, Svg, description}: FeatureItem) {