V5 — Déploiement IONOS¶
Commit de référence : à venir.
Contexte¶
V1 a livré une living doc buildable et servable en local (mkdocs serve). ADR 0007 avait explicitement reporté le déploiement à une vague ultérieure. V5 tient cet engagement : publier le site sur https://sdeg.aelworks.fr/.
La reprise démarre sur l'hypothèse d'un VPS Linux IONOS avec SSH root, Caddy TLS auto, rsync atomique — un plan techniquement élégant mais déconnecté de l'infra existante. Le projet voisin kanban-vibe, déjà déployé sur aelworks.fr, utilise une stack radicalement différente : IONOS mutualisé + SFTP + GitHub Actions.
Le pivot a eu lieu au bout de 15 minutes d'échange, après exploration du repo kanban-vibe.
Décisions structurantes¶
Décision 1 — Aligner sur la stack aelworks.fr existante¶
Plutôt que maintenir deux stacks de déploiement différentes pour un même domaine, V5 adopte la stack kanban-vibe : IONOS mutualisé + Dylan700/sftp-upload-action dans GitHub Actions. Cohérence > élégance technique.
Cette décision est formalisée dans ADR 0008, qui supersede implicitement le plan VPS/Caddy initial.
Décision 2 — CI dès V5, pas de déploiement manuel intermédiaire¶
Le plan initial prévoyait npm run deploy en V5, CI en V6+. Inverser l'ordre : CI dès V5, car c'est ce que fait kanban-vibe et un script manuel serait un détour.
Conséquence : les secrets SFTP vivent dans GitHub Secrets, pas dans un .env.deploy local.
Décision 3 — Pas de preview deploys tant que solo direct-to-main¶
La tentation d'ajouter Vercel / Cloudflare Pages / GitHub Pages pour preview par PR a été examinée puis écartée : aucun flux de PR n'existe sur ce repo aujourd'hui. Ajouter un 2e provider = scope creep.
À rouvrir si le repo devient multi-contributeurs.
Décision 4 — Trigger combiné push + workflow_dispatch¶
Le push main déclenche le build. workflow_dispatch permet de rejouer sans commit (utile après rotation de secret, fix DNS, etc.). Filtres paths pour éviter les redéploiements sur commits purement internes (refacto CLI, tests, hooks).
Pivots¶
Abandonné : VPS Linux L + Caddy + rsync atomique¶
Plan le plus propre techniquement : maîtrise totale du serveur, TLS Let's Encrypt, rollback atomique via swap de dossier. Invalidé par la réalité : pas de VPS provisionné, pas d'envie d'en provisionner un pour un site statique, divergence avec kanban-vibe.
Leçon : avant de concevoir un plan d'infra, regarder ce qui existe déjà chez le même hébergeur pour le même domaine.
Abandonné : SFTP manuel local (npm run deploy)¶
Envisagé comme intermédiaire "V5 manuel, V6 CI". Abandonné pour éviter d'écrire un script qui serait obsolète dans la vague suivante.
Abandonné : Vercel preview en plus d'IONOS¶
Examiné après constat que kanban-vibe utilise Vercel pour du preview. Pour sdeg-kernel, le besoin n'existe pas : pas de PR en cours, mkdocs serve local couvre la preview dev.
Artefacts produits¶
.github/workflows/deploy-docs.yml— workflow build + SFTPdocs/adr/0008-deploiement-ionos-sftp-ci.md— décision formaliséedocs/guide/deploiement.md— procédure opérationnelle (prérequis IONOS, secrets GH, rollback, dépannage)docs/journal/v5-deploiement-ionos.md— ce chapitre
Mises à jour :
mkdocs.yml— ajout nav : Guide/Déploiement, Journal/V5, ADR/0008docs/adr/index.md,docs/journal/index.md,docs/guide/index.md— ajout des entrées
Non produits (volontaire) :
- Pas de
tools/deploy/*.sh— la CI remplace. - Pas de
tools/deploy/server/Caddyfile— serveur managé par IONOS. - Pas de script
deploydanspackage.json— idem.
Leçons apprises¶
Le plan d'infra se vérifie contre l'existant avant d'être écrit¶
La reprise V5 portait un plan technique détaillé (VPS, Caddy, rsync, swap atomique, npm run deploy documenté en 150 lignes). Un seul grep dans le repo voisin a suffi à invalider l'hypothèse fondatrice. Le bon geste d'exploration consiste à regarder ce qui tourne déjà chez le même hébergeur, pas à concevoir dans le vide.
Cette leçon est transférable : avant tout plan d'infra impliquant un hébergeur, un CI, un DNS — lister les repos voisins qui partagent la cible et lire leurs workflows. Cinq minutes de lecture économisent souvent une vague entière d'errance technique.
La cohérence multi-projets vaut plus que l'élégance per-projet¶
Un plan VPS/Caddy pour sdeg-kernel aurait été techniquement supérieur (atomic swap, observabilité fine, clé SSH) — mais aurait créé deux mondes opérationnels sur aelworks.fr. Le jour où l'opérateur oublie sur quel projet il utilise quelle stack, la maintenance explose. L'uniformité est une forme de documentation implicite.
Une CI bien triggerée dispense de documenter la procédure de deploy¶
La bascule "manuel → CI" a aussi un bénéfice cognitif : la procédure de déploiement est le fichier .github/workflows/deploy-docs.yml. Pas besoin de maintenir un DEPLOY.md à jour — le workflow est lisible, auto-documentant, et reproductible par définition. Le guide docs/guide/deploiement.md se réduit alors aux prérequis humains (créer le sous-domaine IONOS, configurer les secrets) et au dépannage.
Reporter un sujet dans une ADR crée une dette structurée, pas ignorée¶
ADR 0007 disait explicitement "Non-objectifs : déploiement IONOS. Remis à une vague ultérieure." Cette phrase — 12 mots — a suffi à ce que V5 sache exactement où démarrer, 24 heures plus tard, sans contexte reconstruit à chaud. Reporter explicitement dans une ADR vaut mieux que reporter dans sa tête.
Voir aussi : ADR 0008 · Guide / Déploiement · V4 — As-is synthesis.