Le problème
Reprenons notre boutique en ligne, un monorepo piloté par
moon. Les API Symfony order,
stock et shipping tournent sous
FrankenPHP, et Caddy sert les fronts Vue.js. Chaque API a
son Dockerfile, et chaque front son Caddyfile.
Ces fichiers sont des copies presque identiques. Une mise à jour de l'image de base doit être reportée partout, et une copie finit par être oubliée.
Factoriser semble simple : un seul Dockerfile dans
infra/docker/api/, passé à
docker buildx build --file. Le contexte de
build reste le dossier de chaque API, qui garde ce qui lui
est propre. Mais ce fichier n'appartient plus à aucune API,
et la chaîne de livraison se casse.
La chaîne décide d'après le graphe des projets.
Comme dans
notre article sur les pipelines CI pilotés par moon, la liste des images à reconstruire vient de
moon query projects --affected --downstream deep. Cette liste décide aussi des services à redéployer.
Le fichier partagé n'est dans aucun projet. Tant que chaque API avait sa copie, la modifier rendait cette API affectée. Une fois le fichier déplacé, sa modification ne touche plus aucun projet : la requête renvoie une liste vide.
L'échec est silencieux. Prenons une modification du Dockerfile commun qui corrige une vulnérabilité de l'image de base. Aucun job n'échoue, mais aucune image n'est reconstruite : le correctif n'atteint jamais la production.
Les options
Déclarer le fichier en entrée implicite des tâches
-
Ce qu'elle règle :
implicitInputs, dans un fichier.moon/tasks/*.yml, ajoute le Dockerfile commun aux entrées de toutes les tâches héritées.moon cirelance alors les tâches des API quand il change. -
Ce qu'elle coûte :
moon query projects --affectedne lit pas les entrées des tâches. Un projet n'est affecté que par un fichier modifié dans son dossier, ou par ses relations dedependsOn. La requête de déploiement ne voit donc toujours rien.
Interroger les tâches plutôt que les projets
-
Ce qu'elle règle :
moon query tasks --affectedtient compte des entrées. Avec l'entrée implicite, il liste bien les tâchesdocker-builddes trois API. - Ce qu'elle coûte : ce que l'on déploie est un projet. Il faut reconstruire la liste des projets à partir des cibles, et chaque autre requête en projets garde l'angle mort.
Une copie par service, synchronisée par une tâche
- Ce qu'elle règle : une tâche copie le fichier commun dans chaque API avant le build. La copie vit dans le dossier du projet.
- Ce qu'elle coûte : versionnées, les copies multiplient les diffs et peuvent être modifiées à la main. Générées au build et ignorées par git, elles n'apparaissent dans aucun diff : on retombe sur le problème de départ.
Faire du fichier partagé un projet moon
-
Ce qu'elle règle : le dossier
infra/docker/api/devient le projetdocker-api, sans tâche. Chaque API le déclare dans sondependsOn. Une modification du Dockerfile renddocker-apiaffecté, puis ses dépendants avec--downstream. -
Ce qu'elle coûte : un projet de plus
dans le graphe, et une ligne dans chaque
moon.yml. Un nouveau service qui l'oublie retrouve l'angle mort.
Notre recommandation
Le fichier partagé devient un projet moon sans tâche,
déclaré dans le dependsOn de chaque projet
qui l'utilise.
Le graphe porte alors la même information pour les tâches et
pour les projets.
Pourquoi le graphe, et pas les entrées
moon calcule l'état « affecté » à deux niveaux.
Une tâche est affectée quand un fichier modifié correspond à
ses entrées (inputs).
Un projet est affecté quand un fichier modifié se trouve
sous son dossier. L'état se propage ensuite à ses dépendants
ou à ses dépendances, selon --downstream et
--upstream.
moon query projects --affected ne calcule que
ce niveau : son code ne suit que les projets.
Une entrée implicite, aussi large soit-elle, n'y change donc
rien. Seul un projet qui contient le fichier, relié aux API
par dependsOn, fait entrer ce fichier dans le
calcul.
Le dependsOn sert aussi aux tâches. Une entrée
project://docker-api ajoute tous les fichiers
du projet aux entrées d'une tâche. moon la refuse si
docker-api n'est pas une dépendance du
projet : le dependsOn est la seule
déclaration à tenir.
Un partage opt-out
Le Dockerfile commun est la valeur par défaut, pas une
obligation. Une API qui a besoin d'autre chose pose son
propre Dockerfile à sa racine, et le script de
build le préfère. Elle retire alors
docker-api de son dependsOn :
une modification du fichier commun ne la concerne plus.
Le même modèle pour Caddy
Les fronts Vue.js partagent un Caddyfile,
infra/caddy/spa/Caddyfile, dans le projet
caddy-spa. Un front n'a rien à copier : il
complète ce fichier par des fragments, ou le remplace par le
sien. Le Caddyfile commun importe les fragments de trois
dossiers :
-
Caddyfile.d/global/: dans le bloc d'options globales ; -
Caddyfile.d/site/: dans le bloc du site, pour unheaderou uneredir; -
Caddyfile.d/extra/: au premier niveau, pour un autre site ou un snippet.
Un Caddyfile à la racine du front remplace le
fichier commun. Nous préférons l'ajout au
remplacement : un Caddyfile remplacé ne suit plus le
fichier commun.
Les compromis assumés
Une modification du fichier commun reconstruit et redéploie toutes ses API. C'est le comportement voulu, puisque le fichier est commun. Pour essayer un changement sur une seule API, celle-ci prend temporairement son propre Dockerfile.
--downstream deep emmène aussi les
dépendants des API.
Un front qui dépend de order (permis entre
stacks moon distinctes, sinon
invalid_layer_relationship) est reconstruit
quand le Dockerfile des API change. Nous acceptons ce
surplus : c'est la règle qui reconstruit les services
quand app-contracts change.
Un projet sans code dans le graphe.
docker-api n'a ni tâche ni source applicative,
et chaque API le liste parmi ses dépendances. Le gabarit de
génération des services l'inclut, pour qu'un nouveau service
ne l'oublie pas.
Un Dockerfile commun limité au commun. Ce qui est propre à une API reste dans son dossier, ou passe par une copie optionnelle.
Le signal qui doit faire réexaminer ce choix : des services qui remplacent tous le fichier commun, ou des fragments qui grossissent jusqu'à le contourner. Le partage coûte alors plus qu'il ne rapporte.
Mise en œuvre
Les exemples utilisent moon 2.6, Docker Compose 5.7, Buildx 0.38 et Caddy 2.11.
1. Un projet pour le Dockerfile commun
Le dossier du fichier partagé reçoit un
moon.yml, et le workspace le découvre comme les
autres projets.
# .moon/workspace.yml (extrait)
projects:
- 'services/*'
- 'fronts/*'
- 'infra/*/*/moon.yml'
# infra/docker/api/moon.yml
# Le Dockerfile de toutes les API. Un projet sans tâche : les API le listent
# dans leur dependsOn, pour qu'une modification les rende affectées.
id: docker-api
language: unknown
layer: library
# services/order/moon.yml (extrait)
language: php
layer: application
stack: backend
tags: [symfony, docker]
dependsOn:
- app-contracts
- docker-api
2. Des tâches qui voient leurs dépendances
Les API héritent leurs tâches de .moon/tasks/,
comme dans
notre article sur l'héritage de tâches. Son symfony.yml déclare déjà
project://^ en entrée implicite :
docker-build voit les fichiers de
docker-api. Il reste à choisir le
Dockerfile : docker.yml passe par un
script, et docker-php.yml lui désigne le
fichier commun.
# .moon/tasks/docker.yml (extrait)
inheritedBy:
tag: docker
tasks:
docker-build:
command: $workspaceRoot/tools/docker-buildx.sh --tag app/$project:ci .
# .moon/tasks/docker-php.yml
inheritedBy:
tags:
and: [docker, symfony]
# Après docker.yml (500) : ces arguments suivent sa commande.
order: 600
tasks:
docker-build:
args: [--target, frankenphp_prod]
env:
# Relatif à la racine du dépôt.
SHARED_DOCKERFILE: infra/docker/api/Dockerfile
project://^ désigne tous les projets du
dependsOn. Écrire
project://docker-api dans un fichier hérité
casserait l'opt-out : moon refuserait la tâche de toute
API qui retire la dépendance.
3. Choisir le Dockerfile au build
#!/usr/bin/env bash
# tools/docker-buildx.sh [options de buildx] <contexte>
# Lancé depuis le dossier du projet : construit avec son propre Dockerfile
# s'il en a un, sinon avec le Dockerfile commun de sa stack.
set -euo pipefail
root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
dockerfile="$root/${SHARED_DOCKERFILE:?Dockerfile commun manquant}"
if [[ -f Dockerfile ]]; then
dockerfile=Dockerfile
fi
echo "Dockerfile : $dockerfile" >&2
exec docker buildx build --file "$dockerfile" "$@"
Le tag par commit, le push et le relevé du digest s'ajoutent comme dans notre article sur la promotion par digest.
4. Le Dockerfile commun
# infra/docker/api/Dockerfile
# Le Dockerfile de toutes les API. Contexte de build : le dossier de l'API,
# dont frankenphp/ garde ce qui diffère d'une API à l'autre.
FROM dunglas/frankenphp:1-php8.4 AS frankenphp_base
WORKDIR /app
COPY --link frankenphp/conf.d/10-app.ini $PHP_INI_DIR/conf.d/
COPY --link --chmod=755 frankenphp/docker-entrypoint.sh /usr/local/bin/docker-entrypoint
ENTRYPOINT ["docker-entrypoint"]
CMD ["frankenphp", "run", "--config", "/etc/caddy/Caddyfile"]
# ... extensions PHP, étapes frankenphp_dev et frankenphp_prod ...
5. Vérifier sur un commit sonde
Sur une branche de test, un commit ne modifie que
infra/docker/api/Dockerfile. La commande
MOON_BASE=main MOON_HEAD=HEAD moon query projects
--affected --downstream deep --tasks docker-build
doit alors lister order, stock et
shipping.
Avec la seule entrée implicite, le même essai renvoie une
liste vide, alors que
moon query tasks --affected liste les trois
tâches docker-build. Nous l'avons vérifié avec
moon 2.4.5 et 2.6.5.
Ce commit sonde est aussi la preuve à exiger d'un agent de code qui modifie un fichier partagé.
6. Compose et le Dockerfile hors du contexte
En développement, chaque API se construit avec Docker Compose, comme dans notre note sur FrankenPHP en non root. Compose délègue ses builds à Bake par défaut depuis sa version 2.37.0 (5 juin 2025), et toujours depuis la 5.0.0 (2 décembre 2025).
Bake demande une autorisation (--allow fs.read=...) pour lire un fichier hors de son dossier de travail.
Avant sa version 5.7.0, Compose l'accorde pour le contexte
et les contextes additionnels de chaque service, pas pour le
Dockerfile. De Buildx 0.21.0 à 0.37.1, Bake sautait ce
contrôle avec --progress rawjson, le mode
qu'utilise Compose.
Depuis Buildx 0.37.2 (30 septembre 2026), ce Compose refuse
donc un Dockerfile hors du contexte :
additional privileges requested: pass
"--allow=fs.read=...". Compose 5.7.0 (2 novembre 2026) accorde aussi la lecture
du Dockerfile. Pour les postes restés sur une version
antérieure, le dossier du Dockerfile devient un contexte
additionnel, que Compose autorise.
# services/order/compose.override.yaml
services:
php:
build:
context: .
# Le Dockerfile commun des API : une API qui a le sien retire
# dockerfile et additional_contexts.
dockerfile: ../../infra/docker/api/Dockerfile
# Avant Compose 5.7.0 : autorise Bake à lire le dossier du Dockerfile
# commun. Le Dockerfile n'utilise jamais ce contexte.
additional_contexts:
docker-api: ../../infra/docker/api
target: frankenphp_dev
7. Le Caddyfile commun et ses fragments
# infra/caddy/spa/Caddyfile
# Le Caddyfile de tous les fronts Vue.js. Un front y ajoute des fragments
# (Caddyfile.d/global, site, extra) ou le remplace par son propre Caddyfile.
{
import Caddyfile.d/global/*.Caddyfile
}
import Caddyfile.d/extra/*.Caddyfile
:80 {
root * /usr/share/caddy
import Caddyfile.d/site/*.Caddyfile
encode zstd gzip
try_files {path} /index.html
file_server
}
Un import dont le glob ne trouve aucun fichier
n'est pas une erreur, mais Caddy écrit un avertissement à
chaque démarrage. Le Dockerfile des fronts dépose donc un
fragment vide dans chaque dossier.
Le Caddyfile commun arrive dans l'image par un contexte
nommé, caddy-config.
docker-node.yml donne aux fronts
SHARED_DOCKERFILE: infra/docker/spa/Dockerfile
et l'argument
--build-context
caddy-config=$workspaceRoot/infra/caddy/spa. Chaque front liste caddy-spa et
docker-spa dans son dependsOn,
comme les API listent docker-api.
# infra/docker/spa/Dockerfile
FROM caddy:2.11-alpine
# Un fragment vide par point d'import : Caddy n'avertit plus d'un glob sans fichier.
RUN set -eux; \
for point in global site extra; do \
mkdir -p /etc/caddy/Caddyfile.d/$point; \
touch /etc/caddy/Caddyfile.d/$point/.empty.Caddyfile; \
done
# Le Caddyfile commun, puis les fragments du front et son propre Caddyfile,
# copiés seulement s'ils existent.
COPY --from=caddy-config Caddyfile /etc/caddy/Caddyfile
COPY Caddyfile.[d] /etc/caddy/Caddyfile.d/
COPY Caddyfil[e] /etc/caddy/
COPY dist /usr/share/caddy
Une source de COPY absente fait échouer le
build ("/Caddyfile.d": not found). Une source
qui contient un motif (*, ?,
[...]) est traitée autrement : BuildKit
accepte qu'elle ne corresponde à rien, et ne copie rien.
Caddyfile.[d] ne correspond qu'à
Caddyfile.d : c'est un chemin exact, rendu
optionnel.
La référence du Dockerfile ne décrit pas ce comportement. Il
vient du code du frontend Dockerfile (option
AllowEmptyWildcard), et nous l'avons vérifié
avec BuildKit 0.34.2. Pour un dossier,
COPY copie son contenu, d'où la destination
/etc/caddy/Caddyfile.d/.
8. Prouver l'équivalence avec caddy adapt
Avant de fusionner la migration, nous comparons le JSON que
caddy adapt tire de l'image d'un front, avant
et après.
Notre article sur la preuve d'équivalence d'un
refactoring
détaille la recette, et la façon de juger un écart.
Checklist
- Le fichier partagé dans son propre dossier, déclaré comme projet moon sans tâche.
-
Ce projet dans le
dependsOnde chaque utilisateur, et dans le gabarit de génération. -
Des tâches qui voient leurs dépendances (
project://^ouproject://<id>). -
Une requête de déploiement qui suit les dépendants
(
--downstream). - Un commit sonde sur le seul fichier partagé, qui liste tous ses utilisateurs.
- Le Dockerfile du projet préféré au Dockerfile commun, quand il existe.
-
Compose 5.7.0 ou plus récent, ou le dossier du Dockerfile
en
additional_contexts. - Des copies optionnelles écrites avec un glob à crochets.
- Une configuration Caddy adaptée identique avant et après la migration.
Sources
Versions relevées le 15 novembre 2026 : moon 2.6.5, Docker Compose 5.7.1, Buildx 0.39.0, frontend Dockerfile 1.29.0 et Caddy 2.11.9.
-
moon, commandes
query projects
et
query tasks :
--affected,--downstream,--upstream. -
moon,
configuration de projet :
id,dependsOn,layer,stacket entréesproject://. -
moon,
tâches héritées
(
implicitInputs), héritage des tâches (inheritedBy, fusion deargsetenv) et workspace (projects). - moon, tâches affectées, variables et moon 1.29 : suivi des projets et des tâches affectés.
-
moon, code de la version 2.6.5 :
projets affectés,
query projects,
entrées project://
et
contraintes de couches
(
invalid_layer_relationship, sauf entre stacks distinctes). -
Docker,
docker buildx build
(
--file,--build-context) et référence Dockerfile (COPY, motifs,--from). -
BuildKit,
frontend Dockerfile 1.29.0, conversion de COPY :
AllowEmptyWildcard,CopyDirContentsOnly. -
Docker Compose,
build
(
dockerfile,additional_contexts) et versions 2.37.0, 5.0.0 et 5.7.0. - Docker Compose, issue 14285 et pull request 14325 : lecture du Dockerfile accordée à Bake.
-
Docker Buildx,
docker buildx bake
(
--allow fs.read), version 0.37.2 et avis GHSA-gwr2-q96m-6682. - Caddy, import, try_files, caddy adapt et code des imports : avertissement sur un glob sans fichier.
- Lychen, pull request 271 : une mise en œuvre open source du Dockerfile partagé décrit dans cet article, dans un monorepo moon.
- Lychen, pull request 272 : la même approche appliquée aux Caddyfile, proposée dans le même monorepo.