Référence du Dockerfile multi-stage¶
Inventaire factuel du Dockerfile racine de Kirexo. Pour comprendre pourquoi l'image est bâtie sur Alpine et pourquoi ce découpage en stages, voir l'explication Pourquoi une image Alpine multi-stage. Pour l'inventaire de l'image de développement publiée (outillage embarqué, versions figées, autocomplétion), voir Image de développement kirexo-dev ; pour la stack qui la consomme (services, réseaux, URLs, cibles Castor), voir Worktrees et environnement de développement.
Cette page décrit l'état réel du Dockerfile ; en cas de doute, le fichier fait foi.
Image de base¶
Un unique point de pin, réutilisé par tous les stages :
| Élément | Valeur |
|---|---|
| Image amont | dunglas/frankenphp:1.12.7-php8.5-alpine (version de FrankenPHP épinglée au patch) |
| Mercure embarqué | 0.24.x |
| Distribution | Alpine Linux (branche release courante de l'amont, v3.24) |
| libc | musl |
| Serveur applicatif | FrankenPHP (Caddy + worker PHP) |
Le tag est figé par une instruction FROM — pas un ARG. Les montées de version sont proposées par Renovate (cf. Configurer Renovate) ; castor image:upgrade-tools ne reconnaît pas un tag épinglé au patch (cf. Image de base FrankenPHP).
FrankenPHP 1.13 et au-delà : migrer Mercure dans le même lot
Le tag flottant 1-php8.5-alpine a été abandonné à la sortie de FrankenPHP 1.13.0, qui embarque Mercure 1.0. Celui-ci refuse au démarrage les directives publisher_jwt et subscriber_jwt de frankenphp/Caddyfile hors mode compatibilité (protocol_version_compatibility 8), valeur que le Mercure 0.24 de la 1.12 refuse à son tour. Résultat : FrankenPHP ne démarre plus (the "publisher_jwt", "subscriber_jwt"… directives work only in compatibility mode).
Monter FrankenPHP en 1.13 ou plus impose donc de migrer Mercure dans le même lot : bloc issuer dans le Caddyfile, jetons OAuth 2.0 at+jwt côté application, match= côté abonnés. Guide amont : Mercure — UPGRADE.md.
Les trois stages¶
Le Dockerfile définit trois stages construits en images séparées, chaînés par héritage.
| Stage | Hérite de | Rôle | Utilisateur d'exécution |
|---|---|---|---|
frankenphp_base |
frankenphp_upstream |
Extensions PHP, Composer, Castor. Socle commun. | root |
frankenphp_dev |
frankenphp_base |
Xdebug, Chromium, Node, outillage de développement. | app (UID/GID hôte, défaut 1000:1000) |
frankenphp_prod |
frankenphp_base |
Extension pcntl, composer install --no-dev, sources applicatives, assets compilés, durcissement CVE. |
app (1000:1000, shell /bin/sh) |
frankenphp_dev et frankenphp_prod dérivent tous deux de frankenphp_base (et non l'un de l'autre) : le stage dev n'est jamais embarqué en production. Ces trois stages correspondent aux images kirexo-base, kirexo-dev, kirexo-prod publiées dans le registry (cf. Images publiées dans le registry).
Paquets système par stage¶
Tous les paquets sont installés via apk add --no-cache (un index apk qui n'est jamais écrit dans l'image). Chaque stage a son ou ses appels dédiés.
frankenphp_base¶
| Paquet | Rôle |
|---|---|
acl |
Gestion des ACL POSIX (héritée du template amont). |
curl |
Client HTTP — requis par le HEALTHCHECK (curl -f http://localhost:2019/metrics) et le téléchargement du PHAR Castor. Paquet Alpine distinct de busybox. |
file |
Détection de type MIME. |
gettext |
envsubst (substitution de variables dans les templates de conf). |
git |
Requis par Composer pour les dépendances de type source. |
jq |
Parsing JSON — hooks Claude, statusline, plusieurs jobs CI. Présent dès kirexo-base, donc pas de apk add à la volée côté pipeline. |
unzip |
Décompression des archives dist Composer. |
frankenphp_dev¶
Le stage dev fait plusieurs apk add séparés (pour maximiser le cache de layer) :
apk add --no-cache bash— installé avant la directiveSHELL(cf. Note musl) ;- Chromium et son driver (cf. Chromium épinglé sur une branche Alpine figée) ;
- l'outillage de développement, en un seul appel :
apk add --no-cache \
ca-certificates iproute2 \
musl-utils coreutils procps findutils shadow libcap \
shellcheck bash-completion bats ffmpeg lftp
sudo, iptables, ip6tables, ipset et dnsmasq ne sont pas installés
Ils servaient au pare-feu qui vivait dans le conteneur, démantelé au profit d'un réseau internal sans route et d'un proxy à allowlist qui vit hors du conteneur, dans infra/egress/ (cf. Pourquoi la sortie réseau passe par un proxy à allowlist). Il n'existe aucun chemin d'élévation à root dans le conteneur.
Leur absence se mesure, elle ne se suppose pas : command -v sudo rend 1. C'est aussi ce que vérifie l'invariant de confinement C6 — cf. castor confinement:check.
| Paquet | Rôle |
|---|---|
iproute2 |
Fournit ip — diagnostic réseau des sondes de confinement. |
ca-certificates |
Validation TLS des connexions sortantes — le proxy ne terminant pas le TLS, la chaîne reste vérifiée par le client. |
musl-utils |
Fournit getent (ahosts / ahostsv4 / hosts), absent de busybox/musl — consommé par les sondes de résolution intra-stack. |
coreutils |
date -Iseconds, mktemp, seq — les applets busybox ne garantissent pas ces options. |
procps |
pgrep -x / pkill -x (busybox ne fournit pas -x). |
findutils |
xargs -L 1 (busybox xargs n'a pas -L). |
shadow |
useradd / groupadd (ce stage) et usermod / groupmod (overlay compose) — busybox n'a qu'adduser / addgroup. |
libcap |
setcap cap_net_bind_service sur le binaire FrankenPHP. |
shellcheck |
Linter des scripts shell (cible castor lint:shell). |
bash-completion |
Framework requis par la complétion Castor / Symfony Console. |
bats |
castor test:bash (bats-core 1.x, paquet Alpine bats). |
ffmpeg |
Capture vidéo des démos E2E. |
lftp |
Dépôt FTPS du site vitrine sur le repli OVH (job release:site-deploy, infra/site/deploy.sh, cf. castor site:deploy). L'image tourne en utilisateur non root sans sudo : le paquet ne peut pas être ajouté dans le job. |
git, jq et curl viennent déjà de frankenphp_base — ils ne sont pas redemandés.
frankenphp_prod¶
Le stage prod n'ajoute aucun paquet applicatif ; il exécute un seul appel de durcissement et un paquet de build temporaire :
apk upgrade --no-cache tire les correctifs de sécurité Alpine sur tous les paquets hérités de frankenphp_base (curl, libxml2, expat, ncurses, openssl…). C'est le cœur du gain CVE sur l'image livrée. Il remplace l'ancien apt-get purge --autoremove linux-libc-dev du stage Debian : ce paquet n'existe pas sous Alpine (les headers kernel sont dans linux-headers, non installé par défaut), la purge est donc sans objet.
libcap est installé comme dépendance de build virtuelle (.setcap-deps) puis retiré après le setcap : la capability gravée dans les xattr du binaire survit à la suppression de l'outil, sans laisser libcap en surface d'exécution.
Métadonnées OCI : licence¶
Le stage se termine par un label OCI qui déclare la licence du code embarqué, en identifiant SPDX, juste avant le passage à l'utilisateur app :
| Élément | Valeur |
|---|---|
| Clé | org.opencontainers.image.licenses (annotation prédéfinie de l'OCI Image Spec) |
| Valeur | AGPL-3.0-or-later (expression SPDX) |
| Stage | frankenphp_prod uniquement ; frankenphp_dev ne porte pas ce label |
| Position | Fin de stage, avant USER app:app : un LABEL ne crée pas de couche de fichiers, mais il fait partie de la chaîne de cache ; plus haut, il invaliderait le cache de toutes les instructions suivantes |
| Texte intégral | LICENSE, copié avec le reste du contexte par COPY --link . ./ (cf. Contexte de build filtré par .dockerignore) et présent dans l'image à /app/LICENSE |
Le label surcharge toute valeur héritée de l'image de base. La CI ne passe aucun --label qui l'écraserait.
Lecture du label sur une image construite :
docker image inspect <image> --format '{{ index .Config.Labels "org.opencontainers.image.licenses" }}'
La licence elle-même est présentée dans le README.md racine du dépôt.
Contexte de build filtré par .dockerignore¶
frankenphp_prod est le seul stage qui copie tout le contexte de build :
Les autres COPY du Dockerfile visent des fichiers précis. Une exclusion de .dockerignore ne change donc que le contenu de l'image de production. .dockerignore écarte notamment l'outillage IA de développement (Claude Code, Symfony AI Mate, serveurs MCP) :
Entrée .dockerignore |
Contenu écarté |
|---|---|
.claude |
Agents, hooks et permissions Claude Code. |
.agents |
Dossier local non versionné, présent seulement sur un poste de dev. |
.mcp.json |
Déclaration des serveurs MCP. |
AGENTS.md |
Instructions des agents IA. |
CLAUDE.md |
Instructions projet de Claude Code. |
mate |
Extensions Symfony AI Mate du projet. |
infra/mcp |
Infrastructure des serveurs MCP (le reste de infra/ n'est pas touché). |
.dockerignore écarte aussi des sources qui ne servent pas au runtime de l'application. Ces deux entrées sont, elles aussi, vérifiées par le garde-fou de l'image prod :
Entrée .dockerignore |
Contenu écarté |
|---|---|
site |
Sources du site vitrine, construit à part par castor site:build. |
docs |
Sources de cette documentation mkdocs. |
Les motifs sans / ne s'appliquent qu'à la racine du contexte.
L'exclusion se fait dans .dockerignore, pas par un rm dans le stage : un rm après le COPY crée une nouvelle couche, mais laisse les fichiers dans la couche du COPY, d'où ils restent extractibles.
Les dépendances Composer d'outillage (symfony/ai-mate*, en require-dev) et le namespace App\Mate\ (en autoload-dev) sont déjà absents grâce à composer install --no-dev. Claude Code n'est installé que dans frankenphp_dev.
.dockerignore écarte aussi public/assets : des assets compilés en local (par un asset-map:compile lancé en dev) n'entrent jamais dans le contexte. Le stage les recompile (cf. Construction des assets) ; des fichiers locaux périmés masqueraient sinon une compilation manquante.
Le job CI docker:build-prod vérifie l'absence de ces chemins avant de pousser l'image — cf. Garde-fou de l'image prod avant push de docker:build-prod. Le même contrôle se rejoue côté hôte avec castor docker:check-prod-image.
Construction des assets¶
Le CSS Tailwind et les assets AssetMapper sont construits dans le stage frankenphp_prod, au build de l'image. Le RUN qui suit le COPY --link . ./ enchaîne :
RUN set -eux; \
mkdir -p var/cache var/log; \
composer dump-autoload --classmap-authoritative --no-dev; \
composer run-script --no-dev post-install-cmd; \
php bin/console tailwind:build --minify; \
php bin/console asset-map:compile; \
rm -rf var/tailwind/v*; \
chmod +x bin/console; sync;
| Commande | Effet |
|---|---|
composer run-script --no-dev post-install-cmd |
cache:clear, assets:install, importmap:install. Ne construit ni le CSS Tailwind ni public/assets/. |
php bin/console tailwind:build --minify |
Télécharge le binaire Tailwind (version épinglée par binary_version dans config/packages/symfonycasts_tailwind.yaml) sous var/tailwind/, et produit le CSS minifié var/tailwind/app.built.css. |
php bin/console asset-map:compile |
Écrit public/assets/ : manifest.json, importmap.json et les fichiers versionnés, servis statiquement par FrankenPHP. |
rm -rf var/tailwind/v* |
Supprime le binaire Tailwind téléchargé (plusieurs dizaines de Mo) : il ne sert qu'au build, les assets servis à l'exécution sont ceux de public/assets/. |
Ces deux commandes de build sont nécessaires pour deux raisons :
var/est exclu du contexte par.dockerignore: le CSS Tailwind produit en dev n'arrive jamais dans l'image. Sanstailwind:build, toute page qui étendbase.html.twigrépond 500 avecBuilt Tailwind CSS file does not exist: run "php bin/console tailwind:build".- Hors debug, AssetMapper ne sert aucun asset à la volée : sans
asset-map:compile, les pages seraient servies sans CSS ni JS.
La présence de public/assets/manifest.json et public/assets/importmap.json est contrôlée avant le push de l'image — cf. Garde-fou de l'image prod avant push de docker:build-prod.
Extensions PHP¶
Installées via install-php-extensions (compatible Alpine — il résout les libs musl requises).
| Stage | Extensions | Lib musl résolue automatiquement |
|---|---|---|
frankenphp_base |
apcu fileinfo intl opcache zip pdo_pgsql redis amqp |
icu-libs (intl), libpq / postgresql-libs (pdo_pgsql), rabbitmq-c (amqp), libzip (zip) |
frankenphp_dev |
xdebug |
— |
frankenphp_prod |
pcntl |
— |
L'extension amqp (liée à rabbitmq-c sous Alpine) était le candidat le plus à risque de la migration ; elle est bien résolue par install-php-extensions.
Bloc recipes Symfony Flex
Un install-php-extensions pdo_pgsql supplémentaire figure dans le bloc ###> doctrine/doctrine-bundle ### du Dockerfile (recette Flex). Il est redondant avec l'appel groupé ci-dessus et sans effet (extension déjà installée).
pcntl dans le stage prod¶
L'appel suit immédiatement mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" et précède COPY --link composer.* symfony.* ./ : il n'invalide pas la couche des dépendances Composer.
| Élément | Valeur |
|---|---|
| Stage | frankenphp_prod uniquement. Absente de frankenphp_base et de frankenphp_dev : l'image de développement ne la contient pas. |
| Consommateur | messenger:consume du service worker (compose.prod.yaml), dont le processus PHP est le PID 1 du conteneur. Avec pcntl, il installe un gestionnaire pour SIGTERM et SIGINT : sur docker stop, il finit le message en cours puis sort en 0. Sans elle, le signal est ignoré et le conteneur n'est arrêté que par le SIGKILL de fin de délai de grâce. |
| Côté web | L'extension est chargée aussi par FrankenPHP. Symfony n'appelle les fonctions pcntl_* qu'en console. |
| Garde-fou | infra/image/check-prod-image.lib.sh : prod_image_required_extensions() liste pcntl, la sonde exécutée dans l'image teste extension_loaded("pcntl"), et une absence est rapportée ✗ extension PHP obligatoire absente : pcntl. L'image est alors refusée par castor docker:check-prod-image et par le job docker:build-prod avant le push. |
Le raisonnement (PID 1, signaux, délai de grâce) est dans Pourquoi un worker Messenger dédié et un verrou sur le planificateur.
Binaires installés hors gestionnaire de paquets¶
Ces composants ne viennent pas d'apk : ils sont téléchargés directement ou copiés depuis une image officielle. Castor et glab sont figés par version et vérifiés par SHA-256 avant installation ; Composer est copié depuis son image officielle ; Claude Code passe par npm (integrity SRI).
| Binaire | Stage | ARG version | Source | Vérification |
|---|---|---|---|---|
| Composer | frankenphp_base |
composer:2.10 (tag d'image) |
COPY --from=composer:2.10 |
Image officielle Composer (pas de téléchargement réseau). |
| Castor | frankenphp_base |
CASTOR_VERSION |
github.com/jolicode/castor (PHAR) |
CASTOR_SHA256 via sha256sum -c. |
| glab | frankenphp_dev |
GLAB_VERSION |
gitlab.com/gitlab-org/cli (Go statique) |
GLAB_SHA256 via sha256sum -c. |
| Claude Code | frankenphp_dev |
CLAUDE_CODE_VERSION |
npm install -g @anthropic-ai/claude-code |
dist.integrity SRI validé nativement par npm. |
Les valeurs de ces trois ARG ne sont pas reprises ici : castor image:upgrade-tools les bumpe dans le Dockerfile, et une copie de plus dériverait au premier bump. Elles sont listées en un seul endroit — Versions figées.
Node est installé via apk, pas téléchargé
Node et npm ne figurent plus dans ce tableau : ils proviennent désormais du paquet Alpine nodejs (dépôt community, version épinglée par l'ARG NODE_VERSION, révision -rN comprise), installé dans le stage frankenphp_dev — voir Node depuis le paquet Alpine. L'intégrité est garantie par l'index apk signé, sans SHA-256 manuel.
ToolsUpgrader::buildDockerfileUrls() (castor/src/Image/ToolsUpgrader.php) reconstruit les URLs de Castor et glab pour le pré-check host:check (Node n'y figure plus). Le pin version + SHA-256 de Castor et glab est bumpé par castor image:upgrade-tools.
Chromium épinglé sur une branche Alpine figée¶
Le stage frankenphp_dev installe Chromium et son driver depuis la branche release figée v3.24 d'Alpine, pas depuis le dépôt community « rolling » de la base :
ARG CHROMIUM_ALPINE_BRANCH=v3.24
ARG CHROMIUM_VERSION=152.0.7977.82-r0
RUN apk add --no-cache \
--repository "https://dl-cdn.alpinelinux.org/alpine/${CHROMIUM_ALPINE_BRANCH}/community" \
"chromium=${CHROMIUM_VERSION}" \
"chromium-chromedriver=${CHROMIUM_VERSION}"
| Élément | Valeur |
|---|---|
| Version Chromium | 152.0.7977.82-r0 (Alpine v3.24) — valeur volatile, cf. l'avertissement ci-dessous |
| Branche du dépôt | v3.24 (release figée, mêmes libs que la base) |
| Binaires | /usr/bin/chromium et /usr/bin/chromedriver |
| Paquets | chromium + chromium-chromedriver (même version source → toujours alignés) |
Un smoke-test fail-fast suit immédiatement : il fait échouer docker build si le navigateur ne démarre pas.
chromium --headless=new --no-sandbox --disable-dev-shm-usage --dump-dom about:blank > /dev/null
chromedriver --version
Les flags sont alignés sur PANTHER_CHROME_ARGUMENTS de .env.test. Le rationale du pin sur une branche figée est dans l'explication.
Ce pin casse périodiquement, et la branche figée n'y change rien
La branche release devait ne bumper « que la sécurité dans la même major
Chromium ». C'est inexact : Alpine backporte les majors de Chromium dans ses
branches stables — v3.24/community est passé de 150 à 151 puis 152. Comme le
miroir ne conserve qu'une seule version par paquet, la précédente disparaît
et le docker build échoue sur breaks: world[chromium=<ancienne>].
Il n'y a pas de pin durable à trouver : il faut bumper quand ça casse, et le
tableau ci-dessus est volatile par construction. CHROMIUM_VERSION ne fait
pas partie des ARG managés par castor image:upgrade-tools : rien ne signale
le décalage avant le build.
Remède : lire la version proposée dans le message d'erreur apk
(chromium-<version>: breaks: …), la reporter dans CHROMIUM_VERSION, relancer.
Le smoke-test qui suit reste le vrai garde-fou — c'est lui qui protège d'un
navigateur non démarrable, pas le pin.
Node depuis le paquet Alpine¶
Le stage frankenphp_dev installe Node et npm depuis le paquet Alpine nodejs, sur la branche release figée ciblée par NODE_ALPINE_BRANCH, et non plus depuis un tarball musl téléchargé sur unofficial-builds.nodejs.org :
ARG NODE_VERSION=24.18.1-r0
ARG NODE_ALPINE_BRANCH=v3.24
RUN apk add --no-cache \
--repository "https://dl-cdn.alpinelinux.org/alpine/${NODE_ALPINE_BRANCH}/community" \
"nodejs=${NODE_VERSION}" npm
| Élément | Valeur |
|---|---|
| Version Node | NODE_VERSION (ex. 24.18.1-r0, révision Alpine -rN comprise) |
| Branche du dépôt | NODE_ALPINE_BRANCH (v3.24, release figée — mêmes libs que la base) |
| Dépôt | nodejs est servi par main ; le --repository community n'est ajouté que pour npm, absent de main |
| Binaires | node, npm et npx placés dans le PATH système par le paquet |
| Vérification d'intégrité | Index apk signé (pas de NODE_SHA256, pas de sha256sum -c) |
Un smoke-test fail-fast suit immédiatement (node --version; npm --version) : il fait échouer docker build si Node n'est pas exécutable. npm n'est pas épinglé (il suit Alpine 3.24), ce qui déclenche un DL3018 hadolint attendu et volontaire.
Le rationale (le mirror unofficial-builds rate-limite les runners GitLab.com, Alpine 3.24 package la même version) est dans l'explication.
Renommages de paquets Debian vers Alpine¶
La migration a changé le nom de plusieurs paquets et outils. Ces correspondances sont utiles pour relire l'historique ou un ancien Dockerfile Debian.
| Rôle | Nom Debian | Nom Alpine |
|---|---|---|
| Driver Chromium (Panther/CI) | chromium-driver |
chromium-chromedriver |
Lib AMQP (extension amqp) |
librabbitmq |
rabbitmq-c |
Lib PostgreSQL (extension pdo_pgsql) |
libpq |
postgresql-libs |
getent (résolution hosts) |
fourni par libc-bin (glibc) |
fourni par musl-utils |
| Création d'utilisateur (dev) | useradd / groupadd (paquet passwd) |
useradd / groupadd (paquet shadow) |
| Création d'utilisateur (prod) | useradd / groupadd |
adduser / addgroup (busybox) |
| Headers kernel | linux-libc-dev |
linux-headers (non installé) |
Note musl : bash, shell et création d'utilisateur¶
Alpine ne préinstalle pas bash — /bin/sh est busybox ash. Le Dockerfile en tient compte :
apk add bashavantSHELL: le stagefrankenphp_devbascule surSHELL ["/bin/bash", "-o", "pipefail", "-c"](nécessaire pourpipefailsur les pipelinescurl … | sha256sum -c). Comme la directiveSHELLéchouerait sur/bin/bash: not found,bashest installé juste avant, avec le shell par défaut (ash). bash est aussi requis par les scripts d'infrastructure du dépôt (arrays,mapfile,[[ =~ ]]) — dontinfra/egress/render-allowlist.shet les scripts d'entrée du conteneur.- Complétion Castor dans
/etc/profile.d/: Alpine ne garantit pas de/etc/bash.bashrc. La complétion est écrite dans/etc/profile.d/castor-completion.sh, sourcé par tout shell de login. Cf. Autocomplétion Castor. useradd/groupadden dev,adduser/addgroupen prod : le stage dev installeshadow(pour aligner l'UID/GID hôte viauseradd/groupaddetgetent) ; le stage prod, plus minimal, se contente des applets busyboxadduser/addgroupavec un UID/GID fixe1000:1000et un shell/bin/sh(bash n'est pas installé en prod).