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 ci relance alors les tâches des API quand il change.
  • Ce qu'elle coûte : moon query projects --affected ne 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 de dependsOn. 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 --affected tient compte des entrées. Avec l'entrée implicite, il liste bien les tâches docker-build des 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 projet docker-api, sans tâche. Chaque API le déclare dans son dependsOn. Une modification du Dockerfile rend docker-api affecté, 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.

Le Dockerfile commun devient un projet : sa modification redéploie les trois API Avec un projet moon docker-api dans le dependsOn des API docker-api infra/docker/api/Dockerfile modifié : le projet est affecté order stock shipping dependsOn : les trois API sont affectées requête de déploiement order, stock, shipping Avec une entrée implicite seule le fichier n'appartient à aucun projet aucun projet infra/docker/api/Dockerfile modifié : aucun projet affecté order stock shipping entrée de tâche : seules les tâches le voient requête de déploiement [] : rien n'est reconstruit

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 un header ou une redir ;
  • 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 dependsOn de chaque utilisateur, et dans le gabarit de génération.
  • Des tâches qui voient leurs dépendances (project://^ ou project://<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.