docs: add server and CI/CD guides

2026-07-19 21:09:08 +02:00
parent c8a75cb64a
commit fb3d3b5443
13 changed files with 761 additions and 73 deletions
@@ -0,0 +1,115 @@
+---
+title: Flux complet
+description: Relier le développement, la CI, le registry, le serveur et le rollback.
+---
+
+Voici le parcours complet d'un changement jusqu'à la production.
+
+<Steps>
+  <Step>
+
+  ### Développer un petit changement
+
+  Une branche courte part de `main`. Les hooks locaux donnent un premier retour sans remplacer la CI.
+
+  </Step>
+  <Step>
+
+  ### Ouvrir une pull request
+
+  Le frontend et le backend sont vérifiés en parallèle : lint, tests et build.
+
+  </Step>
+  <Step>
+
+  ### Valider l'image
+
+  La CI construit les Dockerfiles de production et peut lancer les tests d'intégration contre la stack Compose.
+
+  </Step>
+  <Step>
+
+  ### Fusionner sur une branche saine
+
+  La fusion n'est possible que si les contrôles obligatoires et la revue ont réussi.
+
+  </Step>
+  <Step>
+
+  ### Créer une version
+
+  Un tag SemVer, par exemple `v1.4.0`, déclenche la publication d'une image portant le même tag.
+
+  </Step>
+  <Step>
+
+  ### Publier dans le registry
+
+  La CI s'authentifie avec un jeton à portée limitée, pousse l'image et conserve son digest.
+
+  </Step>
+  <Step>
+
+  ### Déployer sur le serveur
+
+  L'environnement `production` libère ses secrets après les protections éventuelles. Une clé SSH dédiée appelle le script de déploiement.
+
+  </Step>
+  <Step>
+
+  ### Vérifier ou restaurer
+
+  Healthchecks, URL publique, journaux et smoke test confirment la version. En cas d'échec, le tag précédent est redéployé.
+
+  </Step>
+</Steps>
+
+## Vue d'ensemble
+
+```text
+branche courte
+     │
+     ▼
+pull request ──► CI ──► revue ──► main
+                                     │
+                                     ▼
+                               tag de version
+                                     │
+                         build + push de l'image
+                                     │
+                                     ▼
+                                  registry
+                                     │
+                          approbation éventuelle
+                                     │
+                                     ▼
+                          serveur ──► healthcheck
+                             │
+                         si échec
+                             ▼
+                      tag précédent
+```
+
+## Critères de passage
+
+| Passage | Condition |
+| --- | --- |
+| pull request → main | tous les contrôles et la revue réussissent |
+| main → version | la branche est livrable et le changelog est prêt |
+| version → registry | l'image est construite et identifiée sans ambiguïté |
+| registry → production | sauvegarde, accès, secrets et approbations sont prêts |
+| déploiement → terminé | healthchecks et smoke test réussissent |
+
+## En cas d'incident
+
+1. arrête les déploiements concurrents ;
+2. collecte le tag, l'heure, les journaux et les changements de configuration ;
+3. redéploie le dernier tag sain si l'incident vient de l'application ;
+4. restaure les données seulement si nécessaire et selon la procédure testée ;
+5. corrige par un nouveau changement versionné, sans modifier le conteneur à la main ;
+6. documente la cause et améliore le contrôle qui aurait pu la détecter.
+
+<Callout title="Définition de terminé" type="success">
+  La pipeline n'est complète que lorsqu'elle sait prouver quelle version tourne, détecter un échec et revenir à un état connu.
+</Callout>
+