@nodefony/devkit 10.0.0-alpha.5 → 10.0.0-alpha.7

package/skills/nodefony-devops/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: nodefony-devops
+metadata:
+  version: 1.0.0
+description: >
+  Exploite CETTE application Nodefony en conteneur : image, compose, frontal, secrets, variables,
+  Kubernetes, Podman. N'enseigne pas Docker — il énonce le CONTRAT d'exploitation, chiffré :
+  quelles sondes elle expose, combien de temps elle draine, quel code de sortie elle rend, sous
+  quel identifiant elle tourne, où elle écrit, ce qui casse quand une variable manque. Sert
+  d'abord à savoir ce qu'il ne faut PAS réécrire. À charger AVANT d'écrire un manifeste, un
+  compose, une étape de déploiement, ou de diagnostiquer un conteneur qui redémarre.
+  Déclencheurs : "déployer mon application en production", "mettre mon app en production",
+  "construire et vérifier l'image", "docker compose", "derrière nginx", "Kubernetes",
+  "mon pod redémarre", "mon pod perd des requêtes", "redéploiement sans coupure",
+  "arrêt gracieux", "readOnlyRootFilesystem", "politique Restricted", "secrets",
+  "mot de passe en production", "variables d'environnement", "Podman", "GitLab CI".
+---
+
+# nodefony-devops — exploiter cette application
+
+> **Maintenance** : vérité courante, jamais un journal. Éditer en place.
+
+Tu sais faire du Docker. Ce que tu ne sais pas encore, c'est ce que **cette** application garantit
+— et ce qu'elle attend de toi. C'est tout ce que porte cette page.
+
+## 1. Le contrat d'exploitation
+
+Ce que l'application tient, sans que tu aies rien à coder. Chiffré, parce qu'un ordonnanceur se
+règle avec des nombres.
+
+| Ce que tu veux                    | Ce qu'elle fait                                                                                                                                                        |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Savoir si le process vit**      | `GET /livez` → `200`. Reste à `200` **pendant tout l'arrêt** : un exemplaire qui draine est vivant, le tuer ferait exactement ce qu'on veut éviter.                    |
+| **Savoir s'il peut servir**       | `GET /readyz` → `503` avant d'être prêt, `200` ensuite, et `503` **dès la première milliseconde du SIGTERM**. C'est lui qui te retire du répartiteur.                  |
+| **Ne pas être cru mort à tort**   | Les deux sondes **court-circuitent le pipeline avant la limitation de débit**. Un agent d'ordonnancement limité recevrait `429`, qu'il lirait comme un échec de sonde. |
+| **Un arrêt propre**               | `SIGTERM` → refus des nouvelles requêtes, on laisse finir celles en vol, borné à **15 s**. Sous les 30 s qu'un kubelet accorde par défaut.                             |
+| **Laisser le répartiteur suivre** | Un délai configurable **avant** le début du drain, le temps que ton frontal retire l'exemplaire de sa table.                                                           |
+| **Vérifier que l'arrêt a marché** | Code de sortie **`0`**. Un **`137`** signifie qu'il a été tué : les requêtes en vol sont perdues, à chaque déploiement, **sans une ligne de journal**.                 |
+| **Un utilisateur non root**       | `USER 1000:1000` — **numérique**, donc utilisable tel quel par un `runAsUser`. Un `USER nom` ne l'est pas, et certains ordonnanceurs le refusent.                      |
+| **Des secrets montés**            | **Toute** variable accepte le suffixe `_FILE` : `NF_CSRF_SECRET_FILE=/run/secrets/csrf` lit le contenu du fichier. Secrets Docker **et** Kubernetes.                   |
+| **Identifier l'exemplaire**       | `NF_POD_NAME` — à alimenter depuis `metadata.name`. Elle dérive l'identité d'origine du bus temps réel ; sans elle, plusieurs exemplaires se confondent.               |
+| **Un port**                       | `5151`, déclaré par `EXPOSE`. Au-dessus de 1024, donc aucune capacité privilégiée n'est requise.                                                                       |
+| **Un contrôle de santé natif**    | `HEALTHCHECK` sur `/readyz`, déjà dans l'image.                                                                                                                        |
+
+**Où l'application écrit — la question qui décide de tout le reste.** Deux dossiers, et deux
+seulement : **`tmp/`** et **`var/`**. Tout le reste du système de fichiers peut être scellé.
+
+> 🔴 **Ces deux dossiers ne sont pas ancrés de la même façon.** `tmp/` est résolu depuis le
+> **répertoire courant du process**, `var/` depuis la **racine de l'application**. Dans l'image
+> livrée les deux coïncident (`WORKDIR /app`). Dès qu'une commande personnalisée change de
+> dossier, ils divergent — et l'application écrit ailleurs que là où tu as monté ton volume,
+> **sans aucune erreur**. Si tu changes le répertoire de travail, vérifie les deux.
+
+## 2. Ce qui est déjà dans ton dépôt
+
+Le générateur a rendu ces fichiers **à ton nom**. Ils ne se recopient pas d'un guide : ils
+s'ajustent.
+
+| Fichier                    | Ce qu'il porte                                                                        |
+| -------------------------- | ------------------------------------------------------------------------------------- |
+| `Dockerfile`               | Image de production multi-étages → [`references/image.md`](references/image.md)       |
+| `.dockerignore`            | Ce qui n'entre jamais dans l'image → [`references/secrets.md`](references/secrets.md) |
+| `compose.yaml`             | Services par profils → [`references/compose.md`](references/compose.md)               |
+| `.env`                     | Les variables → [`references/variables.md`](references/variables.md)                  |
+| `deploy/migrate-job.yaml`  | Le travail Kubernetes des migrations — mode d'emploi en tête du fichier               |
+| `.github/workflows/ci.yml` | La chaîne d'intégration                                                               |
+| `.gitlab-ci.yml`           | La même, pour GitLab                                                                  |
+
+Un fichier absent signifie un preset plus léger à la création. **Le régénérer, pas le réécrire.**
+
+## 3. Ce que tu dois poser en face
+
+Ce que l'application ne peut pas deviner. Chacun de ces oublis produit une dégradation
+**silencieuse** — pas une erreur, pas une alerte.
+
+- **`NF__HTTP__TRUSTPROXY`** dès qu'un frontal termine le TLS. Sans lui, l'application constate un
+  schéma `http` et **un cookie `__Host-` n'est pas émis** : les sessions ne tiennent plus, sans le
+  moindre message. Détail et preuve → [`references/frontal.md`](references/frontal.md).
+- **Deux volumes inscriptibles**, sur `/app/tmp` et `/app/var`, si tu scelles la racine.
+- **Une fenêtre d'arrêt ≥ 30 s**, strictement supérieure au drain de 15 s.
+- **Pas de limite processeur.** Une limite mémoire tue proprement et l'exemplaire redémarre ; une
+  limite processeur, elle, ne tue pas : elle ralentit, en permanence, et ça ne ressemble pas à une
+  limite mais à une application lente.
+- **Une base administrée, jamais dans le cluster** — et le plafond de connexions qui va avec (§6).
+
+## 4. Mise en production — la checklist
+
+Chaque ligne a la commande qui la **prouve**. Une case cochée sans commande est une supposition.
+
+| #   | Le point                                                  | La preuve                                                                                      |
+| --- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 1   | L'image se construit                                      | `docker build -t <app> .`                                                                      |
+| 2   | Elle n'embarque **aucun secret**                          | `npx nodefony image:check <app>` — lit les **couches**, pas l'image aplatie (§5)               |
+| 3   | Elle démarre et se déclare prête                          | `docker run -d --name t <app>` puis `curl -fsS localhost:5151/readyz`                          |
+| 4   | Elle s'arrête **proprement**                              | `docker stop t; docker inspect t --format '{{.State.ExitCode}}'` → doit rendre **`0`**         |
+| 5   | Les variables requises sont posées                        | `npx nodefony doctor --env production`                                                         |
+| 6   | Les secrets sont **montés**, pas dans l'environnement     | Suffixe `_FILE` → [`references/secrets.md`](references/secrets.md)                             |
+| 7   | Les migrations passent **avant** les nouveaux exemplaires | `kubectl apply -f deploy/migrate-job.yaml`, attendre la fin                                    |
+| 8   | Le frontal est **dérivé**, pas écrit à la main            | `npx nodefony proxy:generate nginx`                                                            |
+| 9   | Le schéma constaté derrière le frontal est le bon         | Une requête réelle pose un cookie `__Host-` → [`references/frontal.md`](references/frontal.md) |
+| 10  | Un redéploiement ne perd **aucune** requête               | Charge constante pendant un `rollout restart` ; zéro `5xx`                                     |
+| 11  | La racine du conteneur est **scellée**                    | `--read-only` + volumes sur `/app/tmp` et `/app/var`                                           |
+| 12  | Tu sais ce que tu **ne** peux **pas** garantir            | Podman sans privilèges perd l'adresse du client (§7) — à énoncer, pas à masquer                |
+
+## 5. Symptôme → cause → correction
+
+Le tableau qu'on lit en urgence.
+
+| Symptôme                                                     | Cause                                                                                             | Correction                                                                   |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| L'exemplaire redémarre en boucle, journaux muets             | La sonde de vivacité tombe avant la fin du démarrage                                              | Sonde de démarrage sur `/readyz`, dimensionnée sur le **pire** cas           |
+| Le conteneur sort en **137** à l'arrêt                       | Il a été tué : la fenêtre d'arrêt est ≤ au drain                                                  | Fenêtre ≥ 30 s (Podman : `--stop-timeout 20`, son défaut est **10 s**)       |
+| Des `5xx` **pendant** chaque déploiement                     | Le répartiteur envoie encore du trafic quand le drain a commencé                                  | Un délai avant drain, et un court arrêt avant terminaison                    |
+| Les sessions ne tiennent pas derrière le frontal             | Schéma constaté `http` → le cookie `__Host-` n'est pas émis                                       | `NF__HTTP__TRUSTPROXY`                                                       |
+| Les journaux d'audit montrent tous la **même adresse**       | L'adresse du client n'est pas propagée, ou le frontal n'est pas de confiance                      | `trustProxy` ; en Podman sans privilèges, **c'est irréparable** (§7)         |
+| `EACCES` au premier démarrage sur un volume                  | Le volume est né `root:root` : monté **par-dessus** un dossier dont l'image avait fixé le porteur | Volume nommé (il hérite du porteur) ou groupe de système de fichiers         |
+| La base refuse des connexions dès qu'on monte en exemplaires | Une base administrée les compte ; le pool n'est pas borné                                         | Réduire les exemplaires — le plafond n'est pas encore réglable (§6)          |
+| La sonde répond `429`                                        | Ce n'est **pas** la sonde : c'est la limitation de débit — donc l'appel n'a pas pris le raccourci | Interroger `/livez` et `/readyz` nus, sans en-tête ni préfixe ajouté         |
+| Un secret retiré du `Dockerfile` reste dans l'image          | Une couche antérieure le contient encore ; l'effacer plus loin ne l'enlève pas                    | `npx nodefony image:check`, et reconstruire sans jamais l'avoir copié        |
+| La variable posée « ne fait rien »                           | Le nom est faux d'un caractère — une variable inconnue est **ignorée**, pas refusée               | `npx nodefony doctor` → [`references/variables.md`](references/variables.md) |
+
+## 6. Kubernetes — ce qui est rendu, et ce qui te reste
+
+🔴 **Un seul manifeste est rendu à ton nom : `deploy/migrate-job.yaml`.** Le Deployment, le
+Service et l'Ingress ne le sont pas — tu les écris, et les §1 et §3 te disent quoi y mettre.
+
+```bash
+kubectl apply -f deploy/migrate-job.yaml    # les migrations AVANT les exemplaires
+```
+
+**Le manifeste rendu est ton modèle : il est conforme à la politique Restricted.** Recopie-en le
+contexte de sécurité dans ton Deployment — c'est le seul endroit du dépôt où il est déjà juste.
+
+La politique exige six champs. Aucun n'est « fourni par l'image » : ce sont des champs de
+**manifeste**, c'est toi qui les poses. Ce que l'image apporte, c'est de les rendre tous
+satisfaisables :
+
+| Le champ                              | Ce qu'il te coûte                                                                                                                 |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `runAsNonRoot: true`                  | rien                                                                                                                              |
+| `runAsUser` / `runAsGroup` numériques | rien — l'image déclare `USER 1000:1000`, tu reportes `1000`                                                                       |
+| `allowPrivilegeEscalation: false`     | rien                                                                                                                              |
+| `capabilities.drop: ["ALL"]`          | rien — l'application n'écoute qu'au-dessus de 1024                                                                                |
+| `seccompProfile: RuntimeDefault`      | rien — mais **à ne pas oublier** : la politique traite l'**absence** de profil comme une violation, pas comme un défaut permissif |
+| `readOnlyRootFilesystem: true`        | **les deux volumes du §3** — sans eux le conteneur ne démarre pas                                                                 |
+
+**La base de données n'est pas dans le cluster**, et ça a trois conséquences dures →
+[`references/kubernetes.md`](references/kubernetes.md).
+
+Éprouver ton manifeste sans rien laisser derrière :
+
+```bash
+kind create cluster --name <app>
+kubectl label ns default pod-security.kubernetes.io/enforce=restricted   # rend la politique OPPOSABLE
+kubectl apply -f <ton-deployment>.yaml
+kind delete cluster --name <app>
+```
+
+Sans ce label, un manifeste non conforme passe — et on croit avoir prouvé quelque chose.
+
+## 7. Podman
+
+Six écarts avec Docker, dont un qu'on ne répare pas →
+[`references/podman.md`](references/podman.md). Le plus coûteux, parce qu'il est **muet** : en
+mode sans privilèges, l'adresse source du client est perdue. Derrière un frontal, l'audit et toute
+limitation par adresse deviennent faux **sans erreur**. Ça s'énonce, ça ne se masque pas.
+
+`podman kube play` joue tes manifestes **sans cluster** — utile, mais il ne rejoue ni l'admission
+de la politique, ni l'Ingress, ni un déploiement progressif. Ce qu'il ne prouve pas doit être dit.
+
+## 8. Les références
+
+| Fichier                                                | Quand l'ouvrir                                                                          |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| [`references/image.md`](references/image.md)           | Modifier le `Dockerfile` : étages, arguments, bases candidates, ce qui ne se touche pas |
+| [`references/compose.md`](references/compose.md)       | Services, profils, volumes, réseaux, le profil de topologie de production               |
+| [`references/variables.md`](references/variables.md)   | Le catalogue, la grammaire des noms, `_FILE`, **ce qui casse si absent**                |
+| [`references/secrets.md`](references/secrets.md)       | Mots de passe, rotation, couches d'image, ce qui n'entre jamais                         |
+| [`references/frontal.md`](references/frontal.md)       | nginx et haproxy dérivés, TLS, en-têtes, `trustProxy`, `__Host-`                        |
+| [`references/kubernetes.md`](references/kubernetes.md) | Ton Deployment, Restricted, la base administrée                                         |
+| [`references/podman.md`](references/podman.md)         | Les six écarts, et celui qui ne se répare pas                                           |
+
+## 9. Passer la main
+
+| Le besoin                          | Le skill                  |
+| ---------------------------------- | ------------------------- |
+| Coder dans l'application           | `nodefony-dev`            |
+| Faire évoluer le schéma de la base | `nodefony-migrate-schema` |
+| Regarder ou mesurer un écran       | `nodefony-browser`        |
+| Ajouter une entité et son CRUD     | `nodefony-add-crud`       |
+
+## 10. Deux règles qui valent pour tout le reste
+
+- **« Ça construit » ne prouve rien.** Une image qui se construit peut refuser de démarrer, perdre
+  ses requêtes à l'arrêt, ou embarquer une clé. Seule une **exécution** prouve — d'où le §4.
+- **Une variable absente ne lève presque jamais** : elle bascule sur un défaut, et le défaut est
+  souvent raisonnable. C'est ce qui rend l'erreur invisible jusqu'en production. Vérifie ce que
+  l'application a **réellement lu**, pas ce que ton manifeste déclare.

package/skills/nodefony-devops/references/compose.md

@@ -0,0 +1,125 @@
+# Le `compose.yaml` — services, profils, topologie
+
+> **Maintenance** : vérité courante. Éditer en place.
+
+## 1. La règle qui explique tout le fichier : les profils
+
+**Rien de ce qui n'est pas dans un profil actif ne démarre.** Les services d'infrastructure dont
+l'application a besoin — cache, base de données — n'ont **pas** de profil : ils démarrent avec un
+`docker compose up -d` nu. Tout le reste est derrière un profil, et c'est ce qui rend le fichier
+utilisable en développement comme en production.
+
+```bash
+docker compose up -d                        # le décor : cache + base. C'est ce qu'il faut pour `npm run dev`
+docker compose --profile app up -d          # + l'application en conteneur, port publié
+docker compose --profile edge up -d         # la TOPOLOGIE DE PRODUCTION : frontal + application SANS port
+docker compose --profile tools up -d        # les explorateurs de données
+docker compose --profile loki up -d         # journalisation centralisée + tableaux de bord
+docker compose --profile browser up -d      # un navigateur piloté
+```
+
+> Le profil `app` et le profil `edge` sont **exclusifs par nature** : le premier publie un port sur
+> ta machine, le second ne publie rien du tout et laisse le frontal être la seule porte d'entrée.
+> Les lancer ensemble démarre deux exemplaires de l'application.
+
+## 2. Les services
+
+| Service                    | Profil        | Image                                                | Port publié _(sur `127.0.0.1` uniquement)_ |
+| -------------------------- | ------------- | ---------------------------------------------------- | ------------------------------------------ |
+| `redis`                    | _(aucun)_     | `redis:8-alpine`                                     | `6379`                                     |
+| la base _(selon le choix)_ | _(aucun)_     | selon le dialecte retenu à la création               | `5432` ou `3306`                           |
+| `migrate`                  | `app`, `edge` | l'image de l'application                             | aucun                                      |
+| `app`                      | `app`         | l'image de l'application                             | `5251` → `5151`                            |
+| `app-edge`                 | `edge`        | l'image de l'application                             | **aucun, volontairement**                  |
+| `edge`                     | `edge`        | construite avec `--target edge`                      | `8080`, `8443`                             |
+| `redisinsight`             | `tools`       | explorateur du cache                                 | `5540`                                     |
+| `loki` / `grafana`         | `loki`        | journaux et tableaux de bord                         | `3100`, `3000`                             |
+| `browser`                  | `browser`     | navigateur piloté (image **épinglée par empreinte**) | `3001`                                     |
+
+**Les ports sont publiés sur la boucle locale**, pas sur `0.0.0.0`. Une base de développement
+accessible depuis le réseau est une base de développement qui finit indexée.
+
+Le service de la base n'existe que si tu as retenu un dialecte serveur à la création. En SQLite, il
+n'y a pas de service : la base est un fichier dans le volume de l'application.
+
+## 3. L'ordre de démarrage — et le service `migrate`
+
+C'est le point du fichier qui mérite d'être lu, parce qu'il encode une règle de production.
+
+```
+redis (sain) ┐
+             ├──► migrate (jusqu'à SUCCÈS) ──► app / app-edge ──► edge (app-edge sain)
+base  (saine)┘
+```
+
+`app` ne démarre pas sur `migrate` _lancé_, mais sur `migrate` **terminé avec succès**. Un schéma à
+jour avant le premier exemplaire, toujours, sans que tu aies à t'en souvenir. Si `migrate` échoue,
+l'application **ne démarre pas** — c'est le comportement voulu : mieux vaut pas d'application qu'une
+application qui écrit dans un schéma qu'elle ne comprend pas.
+
+Les dépendances vers le cache et la base attendent leur **état de santé**, pas leur démarrage.
+
+## 4. Les deux ancres partagées
+
+Le fichier ne se répète pas : trois services de l'application dérivent d'un même modèle.
+
+| Ancre           | Ce qu'elle porte                                                                                                                          |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `x-app-env`     | L'URL de la base — pointée vers le **nom de service** du compose, pas `127.0.0.1` — et l'URL du cache                                     |
+| `x-app-service` | La construction, le nom d'image local, `restart: unless-stopped`, le réseau, les volumes, **`stop_grace_period: 20s`** et les dépendances |
+
+> 🔴 **`stop_grace_period: 20s` n'est pas décoratif.** Le défaut de Docker est **10 s**, et le drain
+> de l'application est borné à **15 s** : au défaut, chaque `docker compose down` tuerait
+> l'application au milieu de son drain — code de sortie `137`, requêtes en vol perdues, aucun
+> message. Si tu écris ton propre compose, reporte ce réglage.
+
+> 🔴 **L'URL de la base du compose ne se reporte JAMAIS dans un manifeste Kubernetes.** Elle
+> désigne un service du compose ; le même nom dans un cluster désigne un Service qui n'existe pas.
+> Rien ne casse au déploiement, tout casse au premier accès.
+
+## 5. Le profil `edge` — la topologie de production, en local
+
+C'est le profil qui mérite le plus d'attention : il reproduit une production, sur ta machine.
+
+- **`app-edge` ne publie aucun port.** Elle n'est joignable que par le réseau du compose. C'est
+  exactement ce qu'est une application derrière un frontal : injoignable directement.
+- Elle reçoit des variables que `app` n'a pas :
+
+| Variable                     | Valeur           | Pourquoi                                                                                                                         |
+| ---------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `NF__HTTP__TRUSTPROXY`       | `uniquelocal`    | Le frontal est sur le réseau privé du compose. Sans ça, le schéma constaté serait `http` et le cookie `__Host-` ne partirait pas |
+| `NF__HTTP__TRUSTEDHOSTS`     | les hôtes servis | Un `Host` étranger est refusé                                                                                                    |
+| `NF__APP__DOMAINCHECK`       | `"true"`         | Le contrôle de domaine est actif, comme en production                                                                            |
+| `NF__HTTP__STATICS__ENABLED` | `"false"`        | **C'est nginx qui sert les fichiers statiques**, pas l'application                                                               |
+
+- `edge` monte les certificats **en lecture seule depuis le disque** — ils ne sont pas dans
+  l'image. Voir [`secrets.md`](secrets.md).
+- `edge` attend que `app-edge` soit **saine**, pas seulement démarrée.
+
+```bash
+docker compose --profile edge up -d --build
+curl -kfsS https://localhost:8443/          # par le frontal, pas par l'application
+```
+
+## 6. Volumes et réseau
+
+Volumes nommés : un par service qui garde quelque chose — le cache, la base, les explorateurs, les
+tableaux de bord — plus **un pour les données de l'application** (son dossier `var`).
+
+Le réseau est un pont nommé d'après l'application, **sans sous-réseau figé** : figer un sous-réseau
+provoque des collisions dès qu'une autre pile tourne sur la même machine, et le symptôme
+(`Pool overlaps with other one`) ne dit pas laquelle.
+
+## 7. Les gestes courants
+
+```bash
+docker compose ps                                  # ce qui tourne, et l'état de santé
+docker compose logs -f app                         # suivre
+docker compose --profile edge down                 # arrêter CE profil
+docker compose down -v                             # ⚠️ supprime AUSSI les volumes : base et cache PERDUS
+docker compose run --rm migrate                    # jouer les migrations seules
+docker compose config                              # le fichier RÉSOLU — variables substituées
+```
+
+`docker compose config` est le geste qui tranche quand « la variable ne fait rien » : il montre ce
+que Docker a **réellement** compris, substitutions comprises.

package/skills/nodefony-devops/references/frontal.md

@@ -0,0 +1,119 @@
+# Derrière un frontal — nginx, haproxy, Ingress
+
+> **Maintenance** : vérité courante. Éditer en place.
+
+## 1. La configuration se DÉRIVE, elle ne s'écrit pas
+
+```bash
+npx nodefony proxy:generate nginx    [-o <fichier>] [-b <hôte>] [-l <port>] [--reencrypt]
+npx nodefony proxy:generate haproxy
+```
+
+La commande **démarre l'application sans ouvrir de port**, lit ses montages statiques réels, sa
+taille de corps maximale et son battement de cœur temps réel, puis écrit la configuration.
+
+**Pourquoi ça compte** : une configuration écrite à la main est juste le jour où on l'écrit. Au
+premier dossier statique ajouté, à la première route de téléversement, elle devient fausse — et
+elle ne le dit pas : elle sert un 404 ou un 413 que personne ne rattache à la configuration du
+frontal.
+
+Dans l'image, cette génération est un étage de construction : la configuration est produite **au
+moment où l'image est construite**, donc à partir du code exact qu'elle embarque.
+
+## 2. Le point qui casse tout si on l'oublie
+
+🔴 **`NF__HTTP__TRUSTPROXY`**
+
+Quand ton frontal termine le TLS, l'application reçoit du **HTTP en clair**, plus un en-tête qui
+annonce le schéma d'origine. Sans réglage, elle ne croit pas cet en-tête — et c'est la bonne
+position par défaut, parce qu'un en-tête est trivialement falsifiable par un client.
+
+Conséquence si tu ne le poses pas : le schéma constaté est `http`, donc :
+
+- **le cookie `__Host-` n'est pas émis** — ce préfixe impose qu'il soit posé sur une origine
+  sécurisée. Les sessions ne tiennent pas, **sans aucun message** ;
+- l'adresse cliente enregistrée est celle du frontal, donc l'audit et toute limitation par adresse
+  portent sur une seule IP ;
+- les redirections peuvent pointer sur `http://`.
+
+```yaml
+NF__HTTP__TRUSTPROXY: uniquelocal # le frontal est sur un réseau privé
+```
+
+**Le prouver, plutôt que le croire** — c'est un réglage dont l'effet est invisible tant qu'on ne
+regarde pas le bon endroit :
+
+```bash
+curl -ksSI https://<hôte>/
+# dans les en-têtes rendus, un Set-Cookie doit porter le préfixe __Host-
+```
+
+Puis **débranche-le** : retire la variable, redéploie, refais la requête. Le cookie doit tomber. Un
+réglage qu'on n'a jamais vu manquer n'est pas un réglage prouvé.
+
+## 3. Les autres réglages du mode « derrière un frontal »
+
+| Variable                     | À poser                     | Ce qu'elle fait                                                                          |
+| ---------------------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
+| `NF__HTTP__TRUSTEDHOSTS`     | les hôtes réellement servis | Un `Host` étranger est refusé — coupe l'empoisonnement d'en-tête                         |
+| `NF__APP__DOMAINCHECK`       | `"true"`                    | Contrôle du domaine actif                                                                |
+| `NF__HTTP__STATICS__ENABLED` | `"false"`                   | **Le frontal sert les fichiers statiques** ; l'application cesse de les servir en double |
+
+Laisser l'application servir les statiques derrière un frontal qui les sert aussi n'est pas une
+erreur fonctionnelle — c'est un gaspillage silencieux : chaque fichier peut être servi par le
+mauvais des deux, avec des en-têtes de cache différents.
+
+## 4. Ne publie aucun port de l'application
+
+Derrière un frontal, l'application **ne doit publier aucun port**. C'est la définition d'être
+derrière quelque chose : le seul chemin doit passer par le frontal. C'est ce que fait le profil de
+topologie de production du compose — l'application n'y a aucune ligne `ports:`.
+
+Si tu publies quand même un port « pour déboguer », tu as deux portes d'entrée, dont une sans TLS,
+sans limitation et sans les en-têtes que ton frontal pose. Utilise `docker compose exec` ou un
+transfert de port temporaire.
+
+## 5. Les sondes, vues du frontal
+
+Ton frontal a besoin de savoir quand retirer un exemplaire. Les deux sondes ne servent pas à la
+même chose :
+
+| Sonde     | Pour quoi                       | Pendant l'arrêt |
+| --------- | ------------------------------- | --------------- |
+| `/livez`  | « le process est-il vivant ? »  | **reste `200`** |
+| `/readyz` | « peut-il prendre du trafic ? » | passe à `503`   |
+
+**Ton frontal doit sonder `/readyz`**, jamais `/livez` : c'est `/readyz` qui bascule dès le début de
+l'arrêt, donc c'est lui qui te fait retirer l'exemplaire **avant** qu'il cesse de répondre. Un
+frontal qui sonde `/livez` garde l'exemplaire dans sa table pendant tout le drain et envoie du
+trafic à quelque chose qui refuse déjà.
+
+Les deux répondent **avant la limitation de débit**. Si tu obtiens un `429` sur une sonde, ce n'est
+pas la sonde que tu as appelée : vérifie que tu interroges bien le chemin nu, sans préfixe ajouté
+par une règle de réécriture.
+
+## 6. En Kubernetes — l'Ingress, pas une configuration nginx
+
+Le frontal dérivé sert pour une machine, un compose, une machine virtuelle. **Dans un cluster, ce
+rôle appartient au contrôleur d'Ingress**, que tu as choisi et que l'application ne connaît pas.
+
+Donc : un `Ingress` standard — chemins, TLS, taille de corps en annotation — et non une
+configuration nginx générée, qui ne fonctionnerait qu'avec un seul contrôleur.
+
+Ce qui reste vrai, et ce qui change :
+
+| Point                           | Avec un frontal à toi | Avec un Ingress                    |
+| ------------------------------- | --------------------- | ---------------------------------- |
+| `NF__HTTP__TRUSTPROXY`          | **obligatoire**       | **obligatoire**                    |
+| `NF__HTTP__TRUSTEDHOSTS`        | recommandé            | recommandé                         |
+| Configuration dérivée           | oui                   | non — un `Ingress`                 |
+| Qui sert les fichiers statiques | le frontal            | l'application, ou un service dédié |
+
+## 7. Sous Podman sans privilèges — ce qu'on ne peut pas réparer
+
+L'adresse source du client **est perdue** : le trafic arrive depuis la passerelle de redirection.
+Derrière un frontal, l'en-tête d'adresse d'origine porte donc la passerelle, pas le client.
+
+Ce n'est pas un réglage à trouver : c'est une propriété du mode sans privilèges. **Énonce-le** —
+ton audit et ta limitation par adresse sont faux, sans aucune erreur pour le signaler. Voir
+[`podman.md`](podman.md).

package/skills/nodefony-devops/references/image.md

@@ -0,0 +1,136 @@
+# L'image — le `Dockerfile` rendu, étage par étage
+
+> **Maintenance** : vérité courante. Éditer en place.
+
+Quatre étages, deux images finales possibles. Tu ne construis normalement que la dernière ; l'étage
+du frontal ne sort que si tu le demandes explicitement.
+
+## 1. La carte
+
+| Étage       | Base                | Ce qu'il fait                                                         | Descend dans l'image finale ? |
+| ----------- | ------------------- | --------------------------------------------------------------------- | ----------------------------- |
+| `build`     | `node:24-alpine`    | Installe, compile, élague les dépendances de développement            | seulement son `/app`          |
+| `proxyconf` | hérite de `build`   | **Dérive** la configuration nginx et rassemble les fichiers statiques | non — étage intermédiaire     |
+| `edge`      | `nginx:1.27-alpine` | Le frontal, avec la configuration dérivée ci-dessus                   | non — cible séparée           |
+| _(final)_   | `node:24-alpine`    | L'application en production                                           | **oui**                       |
+
+```bash
+docker build -t <app> .                      # l'application
+docker build -t <app>-edge --target edge .   # le frontal, seulement si tu le veux
+```
+
+## 2. L'image finale — ce qui te concerne
+
+| Directive     | Valeur                                                                         |
+| ------------- | ------------------------------------------------------------------------------ |
+| `WORKDIR`     | `/app`                                                                         |
+| `USER`        | **`1000:1000`** — numérique, donc reportable tel quel dans un `runAsUser`      |
+| `ENV`         | `NODE_ENV=production`                                                          |
+| `EXPOSE`      | `5151`                                                                         |
+| `CMD`         | `["node_modules/.bin/nodefony", "production"]`                                 |
+| `HEALTHCHECK` | `/readyz`, intervalle 10 s, délai 2 s, **période de démarrage 20 s**, 3 essais |
+
+**`node` est le process n° 1.** Il n'y a pas d'`ENTRYPOINT` d'init : le signal `SIGTERM` arrive
+donc **directement** au process qui sait drainer. N'ajoute pas un init « pour les signaux » — tu
+t'interposerais entre l'ordonnanceur et le seul process qui sait quoi en faire.
+
+### Les deux dossiers inscriptibles
+
+```dockerfile
+RUN mkdir -p /app/tmp /app/var && chown 1000:1000 /app/tmp /app/var
+```
+
+Ils sont créés **et donnés au bon porteur avant** tout montage. C'est ce qui fait qu'un **volume
+nommé** neuf hérite du bon propriétaire : Docker recopie le porteur du dossier sous-jacent. Un
+**montage lié** (`bind`), lui, ne le fait pas — il arrive `root:root`, et le premier `mkdir` de
+l'application échoue en `EACCES`. C'est la cause n° 1 des « ça marche chez moi ».
+
+**Le reste du code appartient à `root`** : l'application tourne en `1000` et ne peut donc pas se
+réécrire elle-même. C'est voulu, et c'est ce qui rend `readOnlyRootFilesystem: true` atteignable
+dès que ces deux dossiers sont montés.
+
+### Les arguments de construction
+
+| `ARG`        | Défaut    | À quoi il sert                             |
+| ------------ | --------- | ------------------------------------------ |
+| `VERSION`    | `"0.1.0"` | Étiquette OCI `image.version`              |
+| `VCS_REF`    | `""`      | Étiquette OCI `image.revision` — le commit |
+| `BUILD_DATE` | `""`      | Étiquette OCI `image.created`              |
+
+Les trois valeurs se relèvent d'abord — `git describe --tags --always` pour l'étiquette,
+`git rev-parse --short HEAD` pour la révision, et l'horodatage UTC au format ISO 8601 — puis se
+recopient dans la commande. Les poser ainsi plutôt que par substitution garde la ligne exécutable
+sous `cmd.exe` et PowerShell autant que sous un shell POSIX.
+
+```bash
+docker build -t <app>:<version> --build-arg VERSION=<version> --build-arg VCS_REF=<sha-court> --build-arg BUILD_DATE=<date-iso-8601-utc> .
+```
+
+Sans eux l'image se construit quand même — avec des étiquettes vides. Une image de production sans
+`revision` est une image dont personne ne saura dire de quel code elle vient.
+
+## 3. Changer la base — c'est prévu, et c'est écrit dans le fichier
+
+Le gabarit porte deux alternatives en commentaire, avec leur mode d'emploi. La règle commune :
+**remplacer les DEUX `FROM`, jamais un seul** — un étage de compilation `alpine` et une exécution
+`slim` produisent des binaires natifs qui ne se chargeront pas.
+
+| Tu veux…                                              | Bascule                                                          | Ce qu'il faut aussi changer                                     |
+| ----------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- |
+| Un paquet natif qui ne publie **pas** de binaire musl | `node:24-slim` (glibc) sur les deux `FROM`                       | rien                                                            |
+| La surface d'attaque minimale                         | `gcr.io/distroless/nodejs24-debian12` en finale, `slim` en build | **`CMD` et `HEALTHCHECK` en `/nodejs/bin/node`** — pas de shell |
+
+Le symptôme d'un mélange musl/glibc est franc : un `.node` introuvable, ou `Error relocating`, **au
+démarrage** — jamais à la construction. L'image se construit parfaitement et ne démarre pas.
+
+## 4. L'étage du frontal — la configuration est DÉRIVÉE
+
+L'étage `proxyconf` lance `proxy:generate` : il démarre l'application **sans ouvrir de port**, lit
+ses montages statiques réels, sa taille de corps maximale et son battement de cœur temps réel, puis
+écrit la configuration nginx. Tu ne l'écris pas à la main, et tu ne la corriges pas à la main : au
+premier fichier statique ajouté, ta correction serait fausse et personne ne le verrait.
+
+Ses arguments :
+
+| `ARG`            | Défaut      | Rôle                                                |
+| ---------------- | ----------- | --------------------------------------------------- |
+| `EDGE_BACKEND`   | `app`       | Le nom par lequel le frontal joint l'application    |
+| `EDGE_HOSTS`     | `localhost` | Les hôtes servis — devient `NF__HTTP__TRUSTEDHOSTS` |
+| `EDGE_HTTP_PORT` | `8080`      | Port en clair                                       |
+| `EDGE_TLS_PORT`  | `8443`      | Port TLS                                            |
+
+Les ports sont **au-dessus de 1024** exprès : le frontal tourne donc sans capacité privilégiée, y
+compris sous Podman sans privilèges.
+
+🔴 **Aucun certificat n'est gravé dans l'image.** Ils se **montent** à l'exécution. Une clé privée
+dans une couche est publiée avec l'image, et l'effacer dans une couche ultérieure ne l'enlève pas —
+voir [`secrets.md`](secrets.md).
+
+L'étage `edge` expose `8080` et `8443`, avec son propre `HEALTHCHECK` sur `/livez` (période de
+démarrage 5 s, plus courte : nginx démarre vite).
+
+## 5. Ce qu'on ne touche pas, et pourquoi
+
+| La ligne                                                             | Pourquoi elle est là                                                                                                                                                        |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--ignore-scripts` à l'installation                                  | Un script d'installation d'une dépendance s'exécute pendant ta construction, avec ton réseau et ton cache. C'est la porte d'entrée classique d'une compromission de chaîne. |
+| `npm ci` si le verrou existe, sinon `npm install`                    | `npm ci` refuse de démarrer sans verrou ; le gabarit doit marcher dans les deux cas                                                                                         |
+| `npm prune --omit=dev` après la compilation                          | Les dépendances de développement sont dans l'image de construction, pas dans la finale                                                                                      |
+| `rm -rf nodefony/config/certificates var tmp` en fin de construction | La matière de développement — certificats auto-signés, base locale — ne descend pas en production                                                                           |
+| Le code laissé à `root`                                              | L'application ne peut pas se réécrire. Condition de la racine scellée.                                                                                                      |
+
+## 6. Vérifier l'image qu'on a RÉELLEMENT construite
+
+```bash
+npx nodefony image:check <app>
+```
+
+Il lit les **couches**, pas l'image aplatie. La différence est tout le sujet : un fichier copié puis
+supprimé plus loin n'apparaît plus dans un conteneur qui démarre, mais il est toujours **dans
+l'archive** — et quiconque tire l'image peut l'extraire. Un contrôle qui regarde l'image aplatie
+serait vert dans le cas exactement le plus fautif.
+
+```bash
+docker history <app> --no-trunc     # d'où vient chaque couche, et son poids
+docker image inspect <app> --format '{{json .Config.Labels}}' | jq   # les étiquettes OCI
+```