Aller au contenu

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 :

FROM dunglas/frankenphp:1.12.7-php8.5-alpine AS frankenphp_upstream
É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

apk add --no-cache acl curl file gettext git jq unzip
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 \
    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

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 :

LABEL org.opencontainers.image.licenses="AGPL-3.0-or-later"

USER app: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 :

COPY --link . ./

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. Sans tailwind:build, toute page qui étend base.html.twig répond 500 avec Built 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

RUN install-php-extensions pcntl

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 bash avant SHELL : le stage frankenphp_dev bascule sur SHELL ["/bin/bash", "-o", "pipefail", "-c"] (nécessaire pour pipefail sur les pipelines curl … | sha256sum -c). Comme la directive SHELL échouerait sur /bin/bash: not found, bash est 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, [[ =~ ]]) — dont infra/egress/render-allowlist.sh et 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 / groupadd en dev, adduser / addgroup en prod : le stage dev installe shadow (pour aligner l'UID/GID hôte via useradd/groupadd et getent) ; le stage prod, plus minimal, se contente des applets busybox adduser/addgroup avec un UID/GID fixe 1000:1000 et un shell /bin/sh (bash n'est pas installé en prod).