corentin_wakdo/docs/journal/2026-04-24--infra-docker.md

# Infrastructure Docker - stack complete + referentiel RNCP

**Date** : 2026-04-24
**Branche** : `feat/infra-docker`
**PR** : a ouvrir vers `dev` apres merge
**Duree estimee** : ~6h (etalee sur 2 sessions de travail)

---

## Ce qui a ete fait

Travaux regroupes en 3 lots sur la branche `feat/infra-docker`, depuis le commit de cadrage `c044d9b`.

### Lot 1 - Scaffold infra et documentation (commits `c5c6bac` a `32924a5`)

- `README.md` projet (10 849 octets) avec section Methodologie BYAN + 64 Mantras, quickstart "serveur-derriere-Traefik", prerequis, avertissement sur le `.env` pre-existant.
- `.env.example` template neutre (`kiosk.example.com`, `admin.example.com`, `traefik_proxy` - RFC 2606 pour les domaines, aucune info d'infra prod leakee).
- `.dockerignore` pour exclure `node_modules`, `.git`, `docs/notes/`, etc. du contexte de build.
- `Makefile` avec 24 cibles, aide auto-generee (`make help`), cible `check-env` qui detecte les variables critiques manquantes et oriente vers un merge plutot qu'un ecrasement du `.env` existant.
- Structure `docs/journal/` (commit) et `docs/notes/` (gitignore, perso).
- Section 17 du `PROJECT_CONTEXT.md` : "Transparence methodologie et usage d'assistants IA", qui declare l'usage conjoint BYAN + Claude Code, precise le scope (ce que l'IA fait / ne fait pas), et documente la politique "zero trailer `Co-Authored-By`" sur les commits.

### Lot RNCP - Referentiel officiel integre et cross-check (commit `324f5cd`)

- PDF du referentiel officiel RNCP 37805 (Webecom V09-11-22, 20 pages) ajoute dans `docs/_ref/rncp-37805-referentiel.pdf`.
- Index texte compact `docs/_ref/rncp-37805-index.md` : les 24 competences et les ~92 criteres des Blocs 1, 2 et 5 (option DevOps) sont transcrits depuis la source primaire, grep-ables et mis a jour avec leur libelle officiel.
- Cross-check des mappings existants : deux citations de criteres etaient incorrectes dans les documents anterieurs (Cr 4.f.1 et Cr 4.f.4 qualifies d'artefacts Git, alors que la lecture de la source primaire les designe comme des soft skills evaluees a l'oral). Correction appliquee dans ce meme commit, sur `docs/journal/2026-04-23--cadrage-projet.md` et sur la section 8 du `PROJECT_CONTEXT.md`.
- Confirmation que la **RGPD (C3.d, Cr 3.d.1 a 3.d.4) est obligatoire pour valider le Bloc 2**, pas un bonus.

### Lot 2 - Stack Docker complete (commit a venir, voir "Liens vers artefacts")

Arborescence `docker/` creee avec 4 services :

```
docker/
  apache/
    Dockerfile         FROM httpd:2.4-alpine + modules
    httpd.conf         main config durcie (ServerTokens Prod, timeouts)
    mpm.conf           tuning MPM event
    vhost.conf         3 vhosts (healthz + kiosk + admin avec FCGI reverse)
  php-fpm/
    Dockerfile         FROM php:8.3-fpm-alpine3.20 + extensions
    php.ini            display_errors/opcache/session/upload
    www.conf           pool dynamic 3-10 workers, TCP :9000
  cron/
    Dockerfile         FROM alpine:3.20 + dcron + mariadb-client
    crontab            backup 03h00 (14j retention) + templates purge/stats
    scripts/backup-db.sh  mysqldump + gzip + rotation + validations
```

`docker-compose.yml` (9 667 octets) orchestre les 4 services sur 2 reseaux (`wakdo_internal` bridge interne + `reverse_proxy` externe partage avec le Traefik hote), 2 named volumes (`wakdo_db_data`, `wakdo_uploads`) et 1 bind-mount (`./var/backups/`).

`.gitignore` mis a jour pour ignorer `/var/` (contenant `var/backups/`) avec commentaire pointant vers `docs/notes/docker-volumes-vs-bind-mounts.md` pour justifier la strategie.

`Makefile` enrichi de deux cibles : `make backup` (dump SQL manuel horodate via le conteneur cron) et `make backup-ls` (liste les dumps existants).

Validation `docker compose config --quiet` : syntaxe OK, seuls warnings sur les variables d'env non-injectees dans le contexte de test (comportement normal quand `.env` n'est pas complete).

---

## Pourquoi - decisions et alternatives

### Decision 1 : Dockerfile custom pour Apache plutot qu'image officielle + bind-mount de la conf

- **Decision retenue** : Dockerfile custom pour wakdo-web, avec `COPY httpd.conf /usr/local/apache2/conf/httpd.conf`.
- **Alternative consideree** : utiliser directement `image: httpd:2.4-alpine` dans le compose, avec un bind-mount `./docker/apache/httpd.conf:/usr/local/apache2/conf/httpd.conf:ro`.
- **Raison du choix** :
  1. Homogeneite avec les autres services. Sur 4 services, **3** doivent etre custom par necessite (php-fpm pour installer les extensions, cron pour embarquer le crontab, seul `db` restait eligible a une image officielle sans modification). Faire Apache en image officielle + bind-mount aurait cree une exception a justifier dans la documentation.
  2. Image autosuffisante : le resultat du `docker build` contient toute la conf, aucun risque que la conf soit manquante sur le serveur cible si un fichier bind-mounte disparait.
  3. Lisibilite a l'oral : *"j'ai 4 Dockerfiles qui embarquent la conf de leur service"* est plus clair pour le jury que *"3 Dockerfiles et un bind-mount"*.
  4. Cout marginal faible : 2 lignes de Dockerfile, rebuild en ~15 secondes sur une image Alpine + un COPY. Pendant le dev, la conf Apache est touchee rarement une fois le vhost stable.
- **Trace technique** : Cr 7.c.3 du referentiel (*"L'application complete est correctement conteneurisee avec les services et les dependances"*) est renforce par le fait que toute la conf vit dans les images versionnees.

### Decision 2 : Named volumes pour BDD et uploads, bind-mount pour les backups

- **Decision retenue** :
  - MariaDB → `wakdo_db_data` (named volume).
  - Uploads images produits → `wakdo_uploads` (named volume).
  - Backups SQL du cron → `./var/backups/` (bind-mount).
- **Alternative consideree** : tout en bind-mount vers `./data/`, pour avoir une vue hote unifiee.
- **Raison du choix** : MariaDB cree ses fichiers avec UID 999 dans le conteneur, en bind-mount cela donne des fichiers que l'hote voit comme appartenant a un utilisateur inexistant (`rm -rf` impossible sans sudo). Les named volumes laissent Docker gerer cette isolation. Les backups, eux, sont des `.sql.gz` qu'on veut pouvoir inspecter et `scp` hors conteneur : le bind-mount a un vrai benefice de visibilite ici, et le script backup s'execute en root dans le conteneur donc pas de probleme de permissions.
- **Source** : la doc Docker Engine (section "Storage") et la doc officielle MariaDB Docker Hub recommandent explicitement les named volumes pour les BDD conteneurisees.
- **Ressource projet** : `docs/notes/docker-volumes-vs-bind-mounts.md` (note perso) documente en detail la difference entre `docker compose down` et `docker compose down -v`, le piege de permissions UID 999, et la strategie retenue.

### Decision 3 : Un seul conteneur Apache pour les 2 FQDN (kiosk + admin)

- **Decision retenue** : wakdo-web sert les deux hosts via 2 vhosts Apache distincts, et Traefik pose 2 routers sur ce meme conteneur via les labels.
- **Alternative consideree** : deux conteneurs Apache distincts (un par FQDN), chacun avec son reseau et sa conf.
- **Raison du choix** :
  1. Le code source est unique (un seul repo, un seul bind-mount `./src:/var/www/html`), donc deux conteneurs partageraient exactement la meme image - duplication inutile.
  2. L'isolation fonctionnelle est deja assuree au niveau vhost Apache : la directive `<FilesMatch "\.php$"> Require all denied </FilesMatch>` dans le vhost kiosk interdit toute execution PHP cote borne, meme si un fichier `.php` se trouvait dans `public/borne/`.
  3. Ressources : un conteneur Apache consomme ~30 Mo RAM au repos, en doubler serait gaspiller pour un projet RNCP qui tourne sur un VPS modeste.
- **Critere RNCP** : Cr 7.a.1 (*"analyse des contraintes infrastructure et securite"*) : l'isolation est justifiee par la conf applicative, pas par la multiplication des conteneurs.

### Decision 4 : PHP-FPM pool dynamic 3-10 workers, pas de socket Unix

- **Decision retenue** : `listen = 0.0.0.0:9000` (socket TCP), `pm = dynamic`, 3 workers au demarrage jusqu'a 10 au pic.
- **Alternative consideree** : socket Unix (`/var/run/php-fpm.sock`) partage entre conteneurs via volume, reputee offrir un petit gain de performance.
- **Raison du choix du TCP** : partager un socket Unix entre deux conteneurs exige un volume partage qui couple wakdo-web et wakdo-app plus fortement. Le gain de performance d'un Unix socket vs TCP sur localhost est mesure a quelques pourcents dans plusieurs benchmarks publics [CLAIM L4 consensus communaute, a re-checker avant soutenance si la question tombe]. Pour un projet RNCP a trafic modere, la simplicite d'orchestration l'emporte.
- **Raison du choix du pm dynamic 3-10** : un worker PHP-FPM consomme ~30-60 Mo avec les extensions activees. Avec 10 max, le pire cas est ~600 Mo reserve a PHP, ce qui laisse de la marge sur un VPS 2 vCPU / 4 Go RAM pour MariaDB et les autres services.

### Decision 5 : Crontab au format Vixie (dcron) avec retention de 14 jours

- **Decision retenue** : `mariadb:11.4` LTS + conteneur cron Alpine avec `dcron`, backup nocturne 03h00, gzip, rotation 14 dumps.
- **Alternative consideree** : utiliser le cron systeme de l'hote pour declencher `docker exec wakdo-app php /scripts/backup.php`.
- **Raison du choix** : Cr 7.b.3 du referentiel demande explicitement *"planification de taches repetitives (planificateur de tache, cron tab)"* - avoir un conteneur cron distinct materialise clairement cette competence. Le cron hote aurait melange des responsabilites. La retention de 14 jours suit un consensus communaute [CLAIM L4] : suffisant pour detecter un probleme de deploiement + marge de reprise, sans saturer le disque.

---

## Comment - points techniques cles

### Reverse FastCGI Apache -> PHP-FPM

Le coeur du setup est la directive dans `docker/apache/vhost.conf` pour le vhost admin :

```apache
<FilesMatch "\.php$">
    SetHandler "proxy:fcgi://wakdo-app:9000"
</FilesMatch>
```

Apache agit comme un serveur HTTP statique pour les assets (HTML, CSS, JS, images) et relaye toute requete `*.php` vers le pool PHP-FPM via TCP, en utilisant le nom DNS interne `wakdo-app` resolu par le reseau docker `wakdo_internal`. Aucun port 9000 n'est expose a l'hote - seul wakdo-web peut joindre wakdo-app, exactement ce qu'on veut.

Le module `mod_proxy_fcgi` est compile dans l'image `httpd:2.4-alpine` officielle mais pas charge par defaut. On le charge explicitement dans `httpd.conf` :

```apache
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so
```

### Isolation kiosk / admin au niveau vhost

Le vhost kiosk refuse explicitement l'execution PHP :

```apache
<FilesMatch "\.php$">
    Require all denied
</FilesMatch>
```

C'est une defense en profondeur : meme si un fichier `.php` se retrouvait par erreur dans `public/borne/`, il serait servi comme un fichier statique 403, et non execute. Cela materialise la separation Bloc 1 (front vanilla) / Bloc 2 (back PHP) au niveau infra, au-dela de la separation organisationnelle du code source.

### Persistance et strategie de backup

La strategie retenue est la suivante :

- **Named volume `wakdo_db_data`** attache a `/var/lib/mysql`. Survit aux `docker compose down`. Pour une remise a zero, il faut `make clean` (interactif) ou `docker compose down -v` (destructif direct).
- **Conteneur `wakdo-cron`** monte le volume BDD en lecture seule (`wakdo_db_data:/var/lib/mysql:ro`) et peut dumper via `mariadb-client` connecte au reseau interne. Les dumps vont dans `./var/backups/` (bind-mount) pour etre inspectables depuis l'hote.
- Le script `backup-db.sh` valide que le dump fait plus de 512 octets (sanite), compresse en gzip -9, et supprime les dumps plus vieux que 14 jours via `find -mtime +14 -delete`.

### Depend_on avec condition service_healthy

Pour que `make init` soit deterministe, le compose utilise :

```yaml
depends_on:
  wakdo-db:
    condition: service_healthy
```

Cette condition s'appuie sur le healthcheck officiel `healthcheck.sh --connect --innodb_initialized` fourni par l'image MariaDB 11.4. Apache et PHP-FPM ne demarrent qu'une fois la BDD vraiment prete (pas juste "conteneur demarre"). Le Makefile conserve egalement sa cible `wait-db` en ceinture-bretelles avec un timeout de 60s.

---

## Criteres RNCP couverts

Chaque mapping ci-dessous reference le libelle exact transcrit depuis `docs/_ref/rncp-37805-index.md`, lui-meme base sur le PDF officiel.

### Bloc 5 (option DevOps) - tous les criteres touches

- **Cr 7.a.1** : *"Le candidat a bien analyse les contraintes en termes d'infrastructure et de securite"* → documentation dans `README.md`, `PROJECT_CONTEXT.md` sections 5 et 7, et ce journal. Analyse explicite : reseau derriere Traefik existant, TLS gere en amont, pas de binding de ports hote, deux FQDN distincts.
- **Cr 7.a.2** : *"Propose un ensemble de solutions pertinentes pour automatiser tout ou partie du processus"* → `Makefile` (24 cibles, une ligne `make init`), `docker-compose.yml`, conteneur cron.
- **Cr 7.a.3** : *"Interactions avec les activites connexes, autant sur la partie developpement que sur la partie de l'infrastructure"* → la strategie `./src` bind-mount en dev et `COPY` en prod (via override) materialise cette interaction.
- **Cr 7.b.1** : *"Maitrise de la syntaxe d'un langage de script"* → `Makefile` (100+ lignes), `backup-db.sh` (bash strict avec `set -euo pipefail`).
- **Cr 7.b.2** : *"L'automatisation est fonctionnelle et fiabilisee"* → validations dans `backup-db.sh` (variables d'env verifiees, taille min du dump, rotation), exit codes distincts (1, 2, 3).
- **Cr 7.b.3** : *"Planification de taches repetitives (planificateur de tache, cron tab)"* → conteneur `wakdo-cron` avec `dcron` et crontab dedie.
- **Cr 7.c.1** : *"La machine virtuelle creee par le candidat est configuree et operationnelle"* → hebergement Acadenice en VPS (analogue fonctionnel d'une VM) + conteneurs Docker configures.
- **Cr 7.c.2** : *"Le systeme d'exploitation pour conteneur est installe dans la machine d'hebergement virtuelle"* → Docker Engine installe, `docker compose version` disponible.
- **Cr 7.c.3** : *"L'application complete est correctement conteneurisee avec les services et les dependances necessaires"* → 4 services distincts (web, app, db, cron), extensions PHP requises declarees dans le Dockerfile, mariadb-client dans le cron pour le backup.
- **Cr 7.c.4** : *"Le fichier de configuration est renseigne et permet de lancer la stack applicative complete avec une seule ligne commande"* → `make init` exactement, qui fait build + up + wait-db + migrate (futur). C'est litteralement la phrase.
- **Cr 7.d.1** : *"L'architecture serveur est mise en place et fonctionnelle"* → 2 reseaux Docker dont un externe Traefik, 3 volumes, labels Traefik pour 2 routers TLS.
- **Cr 7.d.2** : *"L'application est testee avant deploiement"* → a venir (P7, CI GitHub Actions), reference explicite dans `README.md` section CI/CD.
- **Cr 7.d.3** : *"L'integration et le deploiement continus sont testes et l'application est livree"* → a venir (P7).

### Bloc 2 - criteres deja adresses par l'infra

- **Cr 3.d.4** : *"Les donnees sensibles sont protegees"* → TLS en entree via Traefik, reseau interne isole (aucun port BDD expose a l'hote), mots de passe dans `.env` gitignore. La partie applicative RGPD (Cr 3.d.1 a 3.d.3) est a traiter en P2-P3.
- **Cr 4.e.1** : *"Le programme protege l'integrite des donnees en empechant toute injection d'elements pouvant les compromettre"* → infra prete (PDO dans l'image via `pdo_mysql`), implementation applicative en P2.
- **Cr 4.f.2** : *"L'utilisation de l'outil de travail collaboratif est maitrisee"* → branches `main` et `dev` protegees, flow `feat/*` impose, Conventional Commits, PR obligatoire.

---

## Questions anticipees du jury

- **Q** : *"Pourquoi un conteneur dedie pour le cron plutot qu'un cron systeme sur l'hote ?"*
  **R** : Trois raisons. D'abord, la reproductibilite : le conteneur cron est defini dans le repo et monte partout ou la stack tourne, alors qu'un cron hote exige de configurer chaque serveur manuellement. Ensuite, la trace RNCP : le Cr 7.b.3 demande explicitement un planificateur, avoir un conteneur distinct materialise clairement cette competence. Enfin, l'isolation : les scripts du cron ont leurs propres dependances (mariadb-client, gzip) qui n'ont pas a polluer l'hote.

- **Q** : *"Votre `docker-compose.yml` ne binde aucun port sur l'hote, meme pas pour la BDD - comment vous connectez-vous a MariaDB depuis votre poste pour inspecter ?"*
  **R** : Via `make shell-db` qui ouvre un `mariadb -u root -p` dans le conteneur `wakdo-db`. C'est volontaire : si on bindait le 3306 hote, on exposerait la BDD a tout le reseau local du serveur, alors qu'elle n'a strictement aucune raison d'etre joignable ailleurs que depuis wakdo-app et wakdo-cron. Pour un client graphique (DBeaver, TablePlus) on peut faire un tunnel SSH qui forward le port en local.

- **Q** : *"Qu'est-ce qui se passe si votre Traefik hote tombe ?"*
  **R** : Les services internes continuent de tourner (Apache continue de servir sur son port 80 interne), mais le site devient injoignable publiquement. On peut constater ce cas via `make ps` + `make logs-web`, et en attendant la restauration du Traefik on peut ouvrir temporairement un tunnel SSH pour acceder au vhost directement. C'est un cas de defaillance documente, pas une architecture resiliente au failover - pour un projet pedagogique, le Traefik unique est accepte.

- **Q** : *"Pourquoi MariaDB et pas MySQL ou PostgreSQL ?"*
  **R** : MariaDB parce que 11.4 est LTS jusqu'en 2028, totalement compatible avec le protocole MySQL (donc PDO avec `mysql:` fonctionne), licence libre sans ambiguite Oracle. PostgreSQL aurait ete defendable aussi - j'ai choisi MariaDB pour rester dans la famille la plus courante en formation dev Web et faciliter la collaboration future avec d'autres developpeurs qui connaitraient MySQL.

- **Q** : *"Comment votre stack protege-t-elle les donnees utilisateurs (RGPD Cr 3.d.4) au niveau infrastructure ?"*
  **R** : Trois couches. Primo, TLS en entree par Traefik (Let's Encrypt automatique, pas de HTTP en clair). Secundo, le reseau Docker interne n'est joignable que depuis les autres conteneurs du projet - la BDD ne parle a personne d'autre que wakdo-app et wakdo-cron. Tertio, les mots de passe BDD vivent dans `.env` gitignore (ni dans le repo, ni dans les images), et les backups sont en bind-mount sur un dossier lui aussi gitignore. Pour la partie applicative (hash mots de passe `argon2id`, cookies `HttpOnly`, Secure, SameSite=Strict), c'est deja prepare dans `php.ini` et dans `.env.example`.

- **Q** : *"Votre note `docs/notes/docker-volumes-vs-bind-mounts.md` est tres detaillee. Qui l'a redigee ?"*
  **R** : Claude Code, sur ma demande, au moment ou nous tranchions la strategie de persistance. Je l'ai lue, annotee mentalement, et je peux en defendre chaque decision. Cette repartition des roles est formalisee dans la section 17 du `PROJECT_CONTEXT.md` - l'IA redige les notes de revision, je valide et je defends le contenu.

---

## Points d'amelioration conscients

- **Absence de `src/`** : le bind-mount `./src:/var/www/html` pointe sur un dossier inexistant au moment ou la stack est livree sur la branche `feat/infra-docker`. Au premier `make init`, Apache servira un `DocumentRoot` vide et renverra des 404. C'est normal : la phase P2 cree les stubs `src/public/borne/index.html` et `src/public/admin/index.php`. Je n'ai pas voulu creer des stubs "Hello Wakdo" juste pour passer un smoke-test, parce qu'ils ressembleraient a du code Bloc 1/2 sans en etre, ce qui brouillerait la lecture du commit courant.
- **Pas de `docker-compose.prod.yml` (override)** : l'absence de fichier override prod est assumee pour l'instant. Le `.env` avec `APP_ENV=prod` et `APP_DEBUG=false` suffit en premiere approche, mais un override est prevu en P7 qui remplacera le bind-mount `./src` par un `COPY` pour figer le code dans l'image de prod et qui durcira `display_errors=0` dans `php.ini`.
- **Pas de `apache2-utils` pour htpasswd** : si un jour on veut proteger `/fpm-status` en Basic Auth, il faudra ajouter le package dans le Dockerfile Apache. Non prioritaire tant qu'on n'expose pas ce endpoint publiquement.
- **Backup SQL local uniquement** : les dumps sont sur le meme serveur que la BDD. Un disque qui plante = on perd tout. Une synchronisation hors-site (rsync, rclone) est a prevoir mais hors scope du RNCP courant.
- **Crons templates desactives** : les lignes de purge sessions et d'agregations stats sont commentees dans le `crontab` parce que les tables concernees n'existent pas encore. Elles seront decommentees en meme temps que les migrations P2-P3 qui les creeront.

---

## Liens vers artefacts

- Commits de la branche `feat/infra-docker` (depuis `c044d9b`) :
  - `c5c6bac` - docs: setup journal structure and session 1 retro
  - `f619f81` - docs: add AI usage transparency section to PROJECT_CONTEXT
  - `5dcc5b8` - docs: add README with methodology and server-behind-traefik quickstart
  - `32924a5` - chore(docker): add env template, dockerignore and Makefile scaffold
  - `324f5cd` - docs: add RNCP 37805 referentiel and fix Cr 4.f mappings
  - (a venir) - feat(docker): complete stack with compose and 4 services

- Fichiers principaux :
  - `docker-compose.yml`
  - `docker/apache/{Dockerfile,httpd.conf,vhost.conf,mpm.conf}`
  - `docker/php-fpm/{Dockerfile,php.ini,www.conf}`
  - `docker/cron/{Dockerfile,crontab,scripts/backup-db.sh}`
  - `Makefile`
  - `.env.example`

- Documentation associee :
  - `README.md` - Quickstart et methodologie
  - `docs/PROJECT_CONTEXT.md` - sections 5, 7, 8, 17
  - `docs/_ref/rncp-37805-index.md` - criteres cibles
  - `docs/notes/docker-volumes-vs-bind-mounts.md` - note revision perso (gitignore)
  - `docs/notes/makefile.md` - note revision perso (gitignore)