Aller au contenu

Déploiement de la living doc

Le site https://sdeg.aelworks.fr/ est publié automatiquement par GitHub Actions sur chaque push main qui touche la doc. Cette page décrit la procédure one-shot de mise en place et l'usage courant.

Rationale

Le choix de la stack (IONOS mutualisé + SFTP + GH Actions) est justifié dans ADR 0008. Toute déviation doit passer par une nouvelle ADR.

Prérequis (one-shot)

1. Espace web IONOS

Dans le panel IONOS (my.ionos.fr) :

  1. Créer un sous-domaine sdeg.aelworks.fr rattaché à un espace web.
  2. Créer un user SFTP dédié à ce sous-domaine (pas réutiliser le user root du compte mutualisé). Noter hostname, username, password.
  3. Vérifier que la racine SFTP du user pointe vers le webroot du sous-domaine (le workflow uploade à ./).

2. DNS

IONOS gère automatiquement le DNS si le sous-domaine est créé via leur panel sur un domaine déjà chez eux. Sinon, ajouter manuellement un record A/CNAME pointant vers l'IP/hostname fourni par IONOS.

Vérifier la propagation :

dig sdeg.aelworks.fr

3. Secrets GitHub

Dans les settings du repo (Settings → Secrets and variables → Actions → Repository secrets), ajouter :

Nom Valeur
SDEG_SFTP_SERVER hostname SFTP IONOS
SDEG_SFTP_USERNAME user SFTP dédié
SDEG_SFTP_PASSWORD password SFTP dédié

Ne jamais committer ces valeurs

Le workflow les lit via ${{ secrets.SDEG_SFTP_* }}. Le repo ne contient aucun secret.

4. Environnement GitHub (optionnel mais recommandé)

Le job deploy est scopé à l'environnement production (environment: production dans le workflow). Créer cet environnement (Settings → Environments → New environment → production) permet :

  • d'ajouter une protection rule (required reviewer, wait timer) si besoin,
  • de scoper les secrets à cet environnement plutôt qu'au repo entier.

Usage courant

Déploiement automatique

Un push sur main qui modifie docs/, mkdocs.yml, requirements-docs.txt, package.json, tools/docs/, sdlc/schema.js, .github/prompts/, .github/agents/ ou README.md déclenche le workflow.

Filtres définis dans .github/workflows/deploy-docs.yml sous on.push.paths. Un commit qui ne touche aucun de ces chemins ne déploie pas — comportement voulu pour éviter des redéploiements inutiles sur des commits purement internes (hooks, tests CLI, refacto sdlc/).

Déploiement manuel

Depuis l'onglet Actions du repo :

  1. Sélectionner Deploy living docs to IONOS.
  2. Cliquer Run workflow → branche main → Run.

Utile pour :

  • rejouer après rotation de secrets,
  • rejouer après correction DNS / IONOS,
  • forcer un redéploiement sans nouveau commit.

Vérification post-deploy

curl -I https://sdeg.aelworks.fr/

Attendu : HTTP/2 200, content-type: text/html, certificat TLS valide (géré par IONOS).

Test visuel rapide :

  • Page d'accueil → https://sdeg.aelworks.fr/
  • Recherche FR accentuée → taper générateur dans la barre
  • Mermaid → vérifier le gitGraph sur /journal/
  • Dates timeago → vérifier le footer "Dernière mise à jour : il y a X" en bas d'une page modifiée récemment

Rollback

Pas de mécanisme d'atomic swap côté SFTP. Pour revenir à un état antérieur :

# 1. Identifier le commit à restaurer
git log --oneline -20

# 2. Revert (génère un nouveau commit)
git revert <sha>

# 3. Push main — redéclenche le workflow
git push origin main

Le revert refait un build propre et re-uploade. Temps total de rollback : ~3–5 minutes.

Pour un rollback urgent sans attendre CI : workflow_dispatch sur un commit antérieur via l'API GitHub ou reset du site/ distant via le client SFTP du panel IONOS (dernier recours).

Dépannage

Le workflow échoue au build

  • mkdocs build --strict : un warning mkdocs échoue le build. Lire les logs, corriger, re-pousser.
  • Plugin git-revision-date-localized : manque fetch-depth: 0 → le checkout n'a pas l'historique. Le workflow a déjà fetch-depth: 0, ne pas y toucher.
  • npm install échoue : pas de package-lock.json dans ce repo (choix volontaire V1). Utiliser npm install, pas npm ci.

Le workflow passe mais le site est vide / 404

  • Vérifier que le sous-domaine IONOS est bien actif et pointe vers le bon webroot.
  • Vérifier que le user SFTP dédié a bien les droits d'écriture à la racine.
  • Vérifier via un client SFTP manuel (FileZilla) que les fichiers sont bien présents après run du workflow.

Le certificat TLS est invalide ou absent

  • IONOS provisionne le cert automatiquement à la création du sous-domaine. Peut prendre 15–60 min.
  • Vérifier dans le panel IONOS que le cert SSL/TLS est bien émis et actif pour sdeg.aelworks.fr.

Les dates "timeago" affichent "build date" partout

  • Le plugin git-revision-date-localized tombe en fallback si l'historique git n'est pas là. Vérifier fetch-depth: 0 dans le workflow (doit être présent au checkout).

Build réussit en local mais échoue en CI

  • Version Node : local via nvm = v24.13.0, CI = v20. Les générateurs tools/docs/*.js sont compatibles Node 18+ (voir package.json engines). Si un jour on utilise une feature Node > 20, mettre à jour le workflow.
  • Version Python : local via .venv/ = 3.x arbitraire, CI = 3.12. Les plugins mkdocs sont épinglés dans requirements-docs.txt et compatibles 3.11+.

Évolutions prévues

  • V6 probable : ajouter preview deploys (Cloudflare Pages ou GitHub Pages) si le repo passe en multi-contributeurs et qu'un flux de PR émerge.
  • Future ADR : passage à une auth par clé SSH si IONOS l'active ou si on change d'action GH.

Voir aussi : ADR 0008 · Journal V5 · Stack technique.