ADR-053 : Extraction du déploiement dans un opt-in¶

Statut¶

Proposé, Forge 1.0.0-beta.x (ticket DEPLOY-EXTRACT-001).
Décision d'architecture ; relève du mainteneur.

Date¶

2026-06-26

Contexte¶

Le déploiement vit aujourd'hui dans le cœur du CLI : cli/deploy/ fournit les
commandes forge deploy:init (génère wsgi.py, une configuration Nginx, une
unité systemd, un README_DEPLOY.md) et forge deploy:check, pour environ 730
lignes.

Trois constats motivent cet ADR :

C'est de l'outillage, pas du runtime. Aucun code de core/ ni d'une
application n'importe cli.deploy : c'est un générateur de configuration
d'exploitation, jamais une brique que l'application appelle à l'exécution.
C'est opinioné. deploy:init suppose Nginx, systemd et Gunicorn. Une
application déployée en Docker, en Kubernetes ou derrière un autre proxy n'a
pas besoin de cette opinion, aujourd'hui cuite dans le cœur du CLI.
Ce n'est pas de la génération de code MVC. La génération du cœur (les
make:*) produit le code applicatif de l'utilisateur (entités, CRUD,
contrôleurs), ce qui est bien du ressort du cœur (ADR-004). Générer une
configuration d'infrastructure relève d'une autre catégorie.

Le dossier deploy/ à la racine du dépôt (sortie régénérable de deploy:init)
a par ailleurs été retiré : le dépôt framework ne porte pas d'application
déployée (ADR-044). La question restante est : la génération de déploiement
elle-même doit-elle rester dans le cœur, ou devenir un opt-in ?

Décision¶

Extraire le déploiement dans un opt-in forge-mvc-deploy (module
forge_mvc_deploy).

Périmètre de l'opt-in :

les commandes forge deploy:init et forge deploy:check ;
les gabarits générés (Nginx, systemd, wsgi.py, README_DEPLOY.md) ;
la documentation de déploiement (docs/deployment/) migrée en doc embarquée du
paquet (ADR-038).

Branchement, fidèle au modèle déjà en place pour les opt-ins à CLI (settings:init,
audit:init, iot:*, etc.) : forge.py dispatche deploy:* vers
forge_mvc_deploy par import paresseux, avec un repli explicite « module non
installé, lancer pip install forge-mvc-deploy ».

forge-mvc-deploy est le premier opt-in à CLI seule (pas d'API runtime
importée par l'application). Ce n'est pas sans précédent : forge-mvc-testing
est déjà un opt-in dev-only sans API métier. L'outillage de déploiement suit la
même logique : on installe la brique quand on en a besoin.

Justification au regard de la charte :

Principe 8 (noyau minimal, briques opt-in) : le déploiement n'est pas du
runtime de framework ; il rejoint les capacités déjà extraites (mail, i18n,
pivot, files, images).
ADR-004 (périmètre du cœur) : le cœur génère du code MVC, pas de la
configuration d'infrastructure.
L'opinion Nginx/systemd/Gunicorn devient opt-in au lieu d'être imposée par
le cœur.

Mise en œuvre (phasage)¶

L'extraction du code, du paquet, de la dispatch, des tests et de la doc
embarquée minimale (présentation + référence CLI) est livrée par
DEPLOY-EXTRACT-001.

La migration des sept guides de mise en production (docs/deployment/) vers la
doc embarquée du paquet est différée à un ticket de suivi dédié
(DEPLOY-DOCS-MIGRATE-001). Ces guides sont fortement intriqués : plus de
quinze liens entrants depuis le reste de docs/ et plusieurs tests qui codent
en dur leurs chemins. Les déplacer dans le même ticket que l'extraction du code
mêlerait deux changements à risques distincts. Dans l'intervalle, le paquet
référence ces guides, qui restent publiés dans la documentation Forge.

Conséquences¶

Le cœur du CLI maigrit (730 lignes et leurs gabarits partent dans l'opt-in).
Le déploiement devient une brique cohérente et autonome : code, gabarits et
documentation au même endroit (doc embarquée ADR-038).
L'onboarding gagne une étape : forge deploy:init exige d'abord
pip install forge-mvc-deploy. Le repli de forge.py guide l'utilisateur.
Premier opt-in à CLI seule : la dispatch forge.py et les garde-fous meta
(table des opt-ins, classifiers, smoke test, doc embarquée, parcours welcome)
s'appliquent comme aux autres paquets.
Les références deploy/... de la documentation restent valides : elles
désignent le dossier généré dans le projet utilisateur, pas le dépôt framework.

Alternatives écartées¶

Laisser le déploiement dans le cœur du CLI. Contredit le principe 8 et
l'ADR-004, et impose l'opinion Nginx/systemd/Gunicorn à tous les projets, y
compris ceux qui déploient autrement.
Documenter sans générer (comme les starters, ADR-035). Les guides
docs/deployment/ existent déjà, mais deploy:check a besoin de code, et les
gabarits générés (config adaptée à upload_max_size, chemins du projet) ont
une vraie valeur qu'un copier-coller manuel perd. L'opt-in garde la génération
utile tout en la rendant optionnelle.
Rattacher le déploiement à un opt-in existant (par exemple
forge-mvc-admin). Mauvais domaine : le déploiement n'a rien à voir avec le
back-office. Une brique dédiée est plus claire (principe 11).

Référence¶

Charte : CHARTE_DOC.md (principe 8, noyau minimal ; principe 11, une seule
façon officielle).
ADR-004 : périmètre du cœur minimal.
ADR-016 : modèle opt-in.
ADR-035 : documenter plutôt que
générer (tension examinée ici).
ADR-038 : documentation embarquée par
paquet.
ADR-044 : le dépôt framework ne porte que le
framework.
cli/deploy/ (code actuel), docs/deployment/ (guides à migrer).