corentin_wakdo/docs/journal/2026-04-30--smoke-test-infra.md

# Smoke test infra Docker — passage prod-ready

**Date** : 2026-04-30
**Branche** : `feat/infra-docker`
**PR** : a creer (suite de la session)
**Duree estimee** : 2h30

---

## Ce qui a ete fait

Validation bout-en-bout de la stack Docker livree en Session 3 (`ac8b6a6`), sur le serveur de deploiement reel.

1. **Fusion `.env`** : le fichier existant ne contenait que les vars `BYAN_API_*` (outil tiers, lit ce fichier). Fusion avec le template `.env.example` Wakdo dans un seul `.env` (gitignore), sans deplacer les vars BYAN. Mots de passe DB generes via `openssl rand -base64 32`.
2. **Switch FQDN** : `corentin-wakdo.acadenice.fr` -> `corentin-wakdo.stark.a3n.fr` (idem admin). Modifie dans `README.md`, `docs/PROJECT_CONTEXT.md`, `.env`. Commit `4edabf2`.
3. **Smoke test `make init`** : echec puis 3 corrections successives, finalement OK avec 4 conteneurs healthy. Commit `d9890cf`.
4. **Validation HTTPS externe** via curl : cert Let's Encrypt provisionne automatiquement par Traefik sur les 2 FQDN, isolation `/healthz` confirmee (non expose publiquement).

---

## Pourquoi — decisions et alternatives

### Decision 1 : Switch FQDN sur `*.stark.a3n.fr` plutot qu'ajout de records sur `acadenice.fr`

- **Decision retenue** : utiliser le wildcard DNS existant sur `*.stark.a3n.fr` (deja configure pour ce serveur).
- **Alternatives** : ajouter 2 records A `corentin-wakdo` et `corentin-wakdo-admin` dans la zone `acadenice.fr`.
- **Raison** : la zone `acadenice.fr` n'a pas de wildcard, son apex pointe vers un autre serveur (`195.15.210.22`), et Traefik d'ici utilise un challenge HTTP-01 (pas DNS-01), donc le FQDN cible doit resoudre vers cet hote *avant* de pouvoir provisionner un cert. Le wildcard `*.stark.a3n.fr` (verifie a coup de `dig` sur des sous-domaines aleatoires : `foo-test-9999.stark.a3n.fr` resout vers `62.210.93.152`) supprime cette etape. Cout : la documentation projet ne reflete plus la branding `acadenice.fr` cible, mais c'est defendable a l'oral comme "sous-domaine d'infrastructure dev sur l'hote stark, branding final restera flexible cote DNS public quand le projet sortira".

### Decision 2 : Subnet explicite `192.168.148.0/24` sur `wakdo_internal`

- **Decision retenue** : declarer un subnet IPAM fixe dans `docker-compose.yml` au lieu de laisser Docker auto-allouer.
- **Alternatives** :
  - `docker network prune` pour liberer 3 reseaux orphelins (~2 /20 + 1 /24)
  - Etendre `default-address-pools` dans `/etc/docker/daemon.json` + restart Docker daemon
  - Subnet en `10.x` plutot que `192.168.x`
- **Raison** : sur cet hote mutualise, l'auto-allocateur Docker echoue (`all predefined address pools have been fully subnetted`) parce que les 15 `/16` du pool par defaut (`172.17.0.0/16` a `172.31.0.0/16`) et 13 sur 16 `/20` du `192.168.0.0/16` sont deja pris par d'autres stacks. Un prune liberait l'instant t mais le probleme reviendrait. Restart du daemon = blast radius eleve (les autres apps de l'hote coupees pendant ~30s). Subnet explicite = deterministe, defendable, isole Wakdo des fluctuations d'allocation auto. Choix de `192.168.148.0/24` : milieu du gap libre `192.168.144-159`, hors collision avec les `/24` acquagest voisins (150, 154, 155, 157), `/24` = 254 IP = right-sized pour 4 services (RFC 1918 `192.168.0.0/16`, classes A/B/C deprecated par CIDR/RFC 1519 depuis 1993).

### Decision 3 : `init: true` sur `wakdo-cron` (au lieu d'installer tini dans le Dockerfile)

- **Decision retenue** : ajouter `init: true` au service `wakdo-cron` dans `docker-compose.yml`, qui declenche l'injection automatique de `tini` par Docker comme PID 1.
- **Alternative** : installer `tini` dans le Dockerfile cron et prefixer le `CMD` par `/sbin/tini --` (comme c'est fait pour `wakdo-app`).
- **Raison** : symptome rencontre = `dcron` boucle sur `setpgid: Operation not permitted` apres demarrage. Cause = un processus tournant en PID 1 dans un namespace PID Linux sans init parent ne peut souvent pas changer son groupe de processus pour ses enfants forkes (limite kernel sur `setpgid()` quand le pere est PID 1). `dcron` exige cette capacite pour isoler chaque job dans son propre process group. La solution canonique = un init reaper (tini, dumb-init, s6-overlay). `init: true` est l'option Docker Compose qui demande au runtime d'injecter automatiquement un init minimal — moins de code que de modifier le Dockerfile, semantique declarative. Trade-off : le wakdo-app utilise son propre `tini` installe explicitement (heritage Session 3) — incoherence stylistique a accepter ou unifier plus tard.

### Decision 4 : healthz servi en fichier statique depuis `/usr/local/apache2/htdocs/`

- **Decision retenue** : `Alias /healthz /usr/local/apache2/htdocs/healthz.txt` + un fichier `healthz.txt` (3 octets, `OK\n`) embarque dans l'image Apache.
- **Alternatives** :
  - `RewriteRule ^/healthz$ - [R=200,L]` (config initiale).
  - `Alias /healthz /var/www/html/public/healthz.txt` (premier essai du fix).
- **Raison** : la directive `R=200` declenche le mecanisme `ErrorDocument` interne d'Apache, qui rend un template HTML generique meme pour un statut 200 — d'ou le body parasite `"The server encountered an internal error or misconfiguration..."` au milieu d'une reponse `200 OK`. Servir un vrai fichier supprime ce comportement. Le fichier doit vivre HORS du chemin bind-monte (`./src` -> `/var/www/html`) qui ecrase le contenu de l'image au runtime, sinon le `COPY` est masque. `/usr/local/apache2/htdocs/` est un chemin Apache natif que le compose Wakdo ne bind-monte pas, donc adapte aux artefacts d'infrastructure.

---

## Comment — points techniques cles

### Saturation des pools d'adresses Docker

Docker daemon alloue les subnets bridge depuis une liste configurable `default-address-pools`. Les valeurs par defaut (cf. [Docker engine source](https://github.com/moby/moby/blob/master/libnetwork/ipamutils/utils.go)) :

```
172.17.0.0/16 -> 172.31.0.0/16   (15 pools de /16)
192.168.0.0/16 carve en /20      (16 pools de /20)
```

Sur cet hote : 15/15 `/16` pris, 13/16 `/20` pris dans `192.168`. Quand `docker network create` (sans `--subnet`) ne trouve aucun bloc contigu disponible, le daemon retourne :

```
Error: all predefined address pools have been fully subnetted
```

C'est un constat operationnel : sur un hote partage qui heberge >30 stacks, declarer ses subnets explicitement est plus une discipline qu'un nice-to-have. La RFC 1918 donne `10.0.0.0/8` (16M IP) presque vide ici, et `192.168.144.0/20` (4096 IP) en gap dans le second pool. Le choix `192.168.148.0/24` reste dans la convention `192.168.x` familiere tout en evitant la collision.

### `setpgid()` et init dans un container PID namespace

Le kernel Linux accorde `setpgid(pid, pgid)` au processus appelant pour changer le pgid de ses enfants, sous conditions (cf. `man 2 setpgid`) :
- l'enfant doit etre dans la meme session
- la cible `pgid` doit appartenir a une session existante
- l'appelant doit avoir des droits sur l'enfant

Quand un processus est PID 1 dans un namespace PID (cas du conteneur sans init explicite), il devient le process group leader d'office et ne peut pas se sortir de son propre PG facilement. `dcron` essaie de mettre chaque job dans un PG isole pour pouvoir l'attacher proprement et envoyer des signaux groupes — il echoue, le job exit 1, `restart: unless-stopped` relance, boucle. L'injection de `tini` (via `init: true` ou `--init`) place tini en PID 1 et `dcron` en PID 2+, donc `dcron` peut faire ses `setpgid()` sans souci.

### Bind-mount masque le COPY de l'image

Comportement Docker : un bind-mount sur un chemin destination ecrase entierement le contenu de l'image a ce chemin. Erreur classique : on `COPY config.txt /var/www/config.txt` dans le Dockerfile, puis on bind-mount `./src:/var/www`, et `config.txt` disparait au runtime. Le COPY a bien lieu *au build*, mais le bind-mount au *run* prend la priorite. C'est ce qui s'est passe pour `healthz.txt` au premier fix.

Solution propre : placer les artefacts d'infrastructure (healthchecks, scripts internes) dans un chemin que le compose ne bind-monte pas (`/usr/local/apache2/htdocs/`, `/opt/app/`, etc.), et reserver `/var/www/html/` au code applicatif bind-monte en dev.

### Validation cert Let's Encrypt sans config DNS prealable

Le wildcard DNS `*.stark.a3n.fr` resout deja `corentin-wakdo.stark.a3n.fr` et `corentin-wakdo-admin.stark.a3n.fr` vers `62.210.93.152`. Au premier hit HTTPS externe, Traefik :

1. Voit le label `traefik.http.routers.wakdo-kiosk.rule=Host(...)` et le `certResolver=letsencrypt`
2. Lance le challenge HTTP-01 : LE leur envoie un GET `/.well-known/acme-challenge/<token>` en HTTP
3. Le FQDN resout vers cet hote -> reponse correcte servie par Traefik (route specifique sur l'entrypoint `web`)
4. LE valide, emet le cert, Traefik le stocke dans `/acme.json` et le sert sur `:443`

Le tout est invisible : pas de config a faire cote Wakdo. La seule contrainte = le FQDN resout vers l'hote *avant* le premier hit. C'etait le bloqueur derriere le switch FQDN en Decision 1.

---

## Criteres RNCP couverts

- **Cr 7.a.1** *("Le candidat a bien analyse les contraintes en termes d'infrastructure et de securite")* : decisions Subnet et FQDN documentent une analyse explicite de l'environnement reel (hote mutualise, pools satures, wildcard disponible, Traefik partage). Pas de copie-colle d'un tutorial generique.
- **Cr 7.a.2** *("...justifie ses choix")* : 4 decisions argumentees avec alternatives evaluees ci-dessus.
- **Cr 7.b.3** *("Mise en place d'un planificateur de tache, type cron tab")* : `wakdo-cron` operationnel (verifie : crontab parse OK, `0 3 * * * backup-db.sh` actif, `init: true` resout les bouclages). Impl detail : `docker/cron/Dockerfile`, `docker/cron/crontab`.
- **Cr 7.c.4** *("...mise en place d'une procedure de deploiement automatisee")* : `make init` deploie l'integralite de la stack en une commande, idempotent, avec checks prealables (.env present, network existant, vars critiques renseignees). Echec cli net si pre-requis manquant.
- **Cr 1.e.4** *("Le candidat a respecte les bonnes pratiques de cloisonnement reseau")* : verifie via curl externe que `/healthz` renvoie 403 quand requis avec un Host applicatif, donc le vhost healthz est bien isole des vhosts publics. Pas de fuite d'observabilite vers l'exterieur dans ce setup.
- **Cr 5.b** *("Journalisation et tracabilite")* : les services redirigent stdout/stderr vers `docker logs` (Apache `ErrorLog /proc/self/fd/2`, php-fpm via tini, dcron `-d 8`, mariadb defaut). `docker compose -p wakdo logs` suffit pour audit.

---

## Questions anticipees du jury

- **Q** : *"Pourquoi avoir fusionne le `.env` BYAN avec celui du projet ? C'est pas du couplage ?"*
  **R** : C'est une dette assumee. L'outil BYAN lit `.env` du dossier de travail ; je n'ai pas creuse comment changer ce chemin sans risquer de casser sa liaison avec son API. La separation en deux fichiers (`docker compose --env-file .env.wakdo`) etait l'option propre, mais cout de modifier le Makefile + risque de regression sur l'outil tiers. J'ai choisi la fusion en sachant que `.env` est gitignore (donc le couplage ne pollue pas le repo public) et documente la raison dans le `.env` lui-meme.

- **Q** : *"Pourquoi `192.168.148.0/24` exactement et pas `10.99.0.0/24` ?"*
  **R** : Choix arbitre par convention de l'ecosysteme local. Les autres stacks de l'hote utilisent souvent `172.x` ou `192.168.x` ; rester dans la meme famille facilite le mental model des admins qui suivront. `10.x` aurait ete plus "datacenter-pro" mais introduit une plage absente des autres stacks de cet hote — visibilite cognitive moindre. C'est un choix de coherence locale, pas une regle universelle.

- **Q** : *"Le redirect HTTP -> HTTPS retourne 404. Est-ce normal ?"*
  **R** : Non. Mes labels Traefik definissent bien un router `wakdo-kiosk-http` sur l'entrypoint `web` avec middleware `redirectscheme`. Le 404 vient probablement d'une interaction avec le middleware global du Traefik d'hote (`redirect-except-acqua@file` declare dans `traefik.toml`) qui s'applique avant et ne match pas mes routers. Ce point est documente comme "a investiguer" dans le SESSION_RESUME ; en pratique l'usage final sera du HTTPS direct via les liens jury, donc non bloquant pour la demo.

- **Q** : *"Comment je sais que `make init` va marcher chez quelqu'un d'autre ?"*
  **R** : Honnetement : il ne marchera pas sans adaptation. Le `.env.example` pointe sur des FQDN neutres (`example.com`, `traefik_proxy`) qu'il faut adapter, et la cible `make init` echoue cleanly avec un message d'aide si le reseau Traefik n'existe pas ou si `.env` manque des vars. Le smoke test ici a valide la chaine sur l'hote stark precis ; un autre hote demanderait probablement un autre subnet (ou un retour a l'auto-alloc si le daemon n'est pas sature).

- **Q** : *"Pourquoi `init: true` plutot qu'installer tini comme dans wakdo-app ?"*
  **R** : Difference de timing. Pour `wakdo-app`, Session 3 a pose tini explicitement parce que c'etait la maniere "showcase" — montrer que je sais l'installer. Pour `wakdo-cron`, c'est apparu en correctif au smoke test ; `init: true` est plus court (1 ligne vs Dockerfile + ENTRYPOINT) et atteint le meme resultat car Docker injecte un init binaire compatible (en realite `docker-init`, qui est tini repackage). Coherence stylistique a faire dans une iteration ulterieure si jugee importante.

---

## Points d'amelioration conscients

- **Redirect HTTP -> HTTPS** : retourne 404 au lieu de 301. Sera traite dans une branche `feat/infra-polish` separee, pas avant validation que ce n'est pas un faux probleme (l'usage demo se fera via lien HTTPS direct).
- **Coherence init** : `wakdo-app` installe tini explicitement, `wakdo-cron` utilise `init: true`. Acceptable en l'etat (les deux marchent), a unifier en passant l'un ou l'autre style si on touche au compose.
- **`docker network prune` pas execute** : 3 reseaux orphelins detectes (`traefik-net`, `crm-chirurgien-network`, `acquagest-prod_acquaprocess_staging`) consomment des subnets sans usage. Pas mon role d'effacer des reseaux que je n'ai pas crees ; signaler a l'admin de l'hote.
- **Pas de DNS-01 + wildcard cert** : Traefik utilise HTTP-01 par FQDN. DNS-01 + wildcard ferait un seul cert pour `*.stark.a3n.fr` et reduirait les renouvellements LE. Mais c'est une optim de l'infra hote, hors scope projet examen.
- **`./src/` vide** : les FQDN repondent 403 sur `/`. Resolution prevue Phase P2 (creation des stubs `public/borne/index.html` et `public/admin/index.php`).

---

## Liens vers artefacts

- **Commits** :
  - `4edabf2` — `docs: switch project FQDN from acadenice.fr to stark.a3n.fr`
  - `d9890cf` — `chore(docker): smoke test fixes for stack startup and healthz`
- **Fichiers principaux modifies** :
  - `docker-compose.yml` (subnet IPAM + `init: true` cron)
  - `docker/apache/Dockerfile` (COPY healthz vers htdocs)
  - `docker/apache/vhost.conf` (Alias healthz)
  - `docker/apache/healthz.txt` (nouveau)
  - `README.md`, `docs/PROJECT_CONTEXT.md` (FQDN switch)
- **Documentation associee** :
  - `docs/journal/2026-04-24--infra-docker.md` (session precedente, decisions architecturales)
  - `docs/notes/docker-volumes-vs-bind-mounts.md` (note technique perso, complement)