The problem

Take our online shop again, a monorepo driven by moon. The Symfony APIs order, stock and shipping run on FrankenPHP, and Caddy serves the Vue.js fronts. Each API has its Dockerfile, and each front its Caddyfile.

These files are near-identical copies. An update of the base image must be carried over everywhere, and one copy ends up forgotten.

Factoring them out looks simple: a single Dockerfile in infra/docker/api/, passed to docker buildx build --file. The build context stays the directory of each API, which keeps what is its own. But that file no longer belongs to any API, and the delivery chain breaks.

The chain decides from the project graph. As in our article on CI pipelines driven by moon, the list of images to rebuild comes from moon query projects --affected --downstream deep. That list also decides which services get redeployed.

The shared file is in no project. As long as each API had its copy, changing it made that API affected. Once the file has moved, a change to it touches no project: the query returns an empty list.

The failure is silent. Take a change to the shared Dockerfile that fixes a vulnerability in the base image. No job fails, but no image is rebuilt: the fix never reaches production.

The options

Declaring the file as an implicit input of the tasks

  • What it solves: implicitInputs, in a .moon/tasks/*.yml file, adds the shared Dockerfile to the inputs of every inherited task. moon ci then reruns the tasks of the APIs when it changes.
  • What it costs: moon query projects --affected does not read task inputs. A project is only affected by a changed file in its directory, or through its dependsOn relations. The deployment query still sees nothing.

Querying tasks instead of projects

  • What it solves: moon query tasks --affected takes inputs into account. With the implicit input, it does list the docker-build tasks of the three APIs.
  • What it costs: what gets deployed is a project. The list of projects has to be rebuilt from the targets, and every other project query keeps the blind spot.

One copy per service, synchronised by a task

  • What it solves: a task copies the shared file into each API before the build. The copy lives in the project's directory.
  • What it costs: committed, the copies multiply the diffs and can be edited by hand. Generated at build time and ignored by git, they appear in no diff: we are back to the original problem.

Making the shared file a moon project

  • What it solves: the infra/docker/api/ directory becomes the docker-api project, with no task. Each API declares it in its dependsOn. A change to the Dockerfile makes docker-api affected, then its dependents with --downstream.
  • What it costs: one more project in the graph, and one line in each moon.yml. A new service that forgets it gets the blind spot back.

Our recommendation

The shared file becomes a moon project with no task, declared in the dependsOn of every project that uses it. The graph then carries the same information for tasks and for projects.

The shared Dockerfile becomes a project: a change to it redeploys all three APIs With a moon project docker-api in the dependsOn of the APIs docker-api infra/docker/api/Dockerfile changed: the project is affected order stock shipping dependsOn : all three APIs are affected deployment query order, stock, shipping With an implicit input only the file belongs to no project no project infra/docker/api/Dockerfile changed: no project is affected order stock shipping task input: only the tasks see it deployment query [] : nothing is rebuilt

Why the graph, and not the inputs

moon computes the "affected" state at two levels. A task is affected when a changed file matches its inputs (inputs).

A project is affected when a changed file sits under its directory. The state then spreads to its dependents or its dependencies, according to --downstream and --upstream. moon query projects --affected only computes this level: its code only follows projects.

An implicit input, however broad, therefore changes nothing here. Only a project that contains the file, linked to the APIs through dependsOn, brings that file into the computation.

The dependsOn also serves the tasks. A project://docker-api input adds all the files of the project to the inputs of a task. moon refuses it if docker-api is not a dependency of the project: the dependsOn is the only declaration to maintain.

Opt-out sharing

The shared Dockerfile is the default, not an obligation. An API that needs something else puts its own Dockerfile at its root, and the build script prefers it. It then removes docker-api from its dependsOn: a change to the shared file no longer concerns it.

The same model for Caddy

The Vue.js fronts share a Caddyfile, infra/caddy/spa/Caddyfile, in the caddy-spa project. A front has nothing to copy: it extends that file with fragments, or replaces it with its own. The shared Caddyfile imports the fragments of three directories:

  • Caddyfile.d/global/: in the global options block;
  • Caddyfile.d/site/: in the site block, for a header or a redir;
  • Caddyfile.d/extra/: at the top level, for another site or a snippet.

A Caddyfile at the root of the front replaces the shared file. We prefer adding to replacing: a replaced Caddyfile no longer follows the shared file.

The trade-offs we accept

A change to the shared file rebuilds and redeploys all its APIs. That is the intended behaviour, since the file is shared. To try a change on a single API, that API temporarily takes its own Dockerfile.

--downstream deep also takes along the dependents of the APIs. A front that depends on order (allowed across distinct moon stacks, otherwise invalid_layer_relationship) is rebuilt when the APIs' Dockerfile changes. We accept this extra work: it is the rule that rebuilds the services when app-contracts changes.

A project without code in the graph. docker-api has neither task nor application source, and each API lists it among its dependencies. The service generator template includes it, so that a new service does not forget it.

A shared Dockerfile limited to what is shared. What belongs to one API stays in its directory, or goes through an optional copy.

The signal that should trigger a review of this choice: services that all replace the shared file, or fragments that grow until they bypass it. Sharing then costs more than it brings.

Implementation

The examples use moon 2.6, Docker Compose 5.7, Buildx 0.38 and Caddy 2.11.

1. A project for the shared Dockerfile

The shared file's directory gets a moon.yml, and the workspace discovers it like the other projects.

# .moon/workspace.yml (excerpt)
projects:
  - 'services/*'
  - 'fronts/*'
  - 'infra/*/*/moon.yml'
# infra/docker/api/moon.yml
# The Dockerfile of every API. A project with no task: the APIs list it
# in their dependsOn, so that a change to it makes them affected.
id: docker-api
language: unknown
layer: library
# services/order/moon.yml (excerpt)
language: php
layer: application
stack: backend
tags: [symfony, docker]
dependsOn:
  - app-contracts
  - docker-api

2. Tasks that see their dependencies

The APIs inherit their tasks from .moon/tasks/, as in our article on task inheritance. Its symfony.yml already declares project://^ as an implicit input: docker-build sees the files of docker-api. What remains is choosing the Dockerfile: docker.yml goes through a script, and docker-php.yml points it to the shared file.

# .moon/tasks/docker.yml (excerpt)
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]
  # After docker.yml (500): these arguments follow its command.
  order: 600
tasks:
  docker-build:
    args: [--target, frankenphp_prod]
    env:
      # Relative to the repository root.
      SHARED_DOCKERFILE: infra/docker/api/Dockerfile

project://^ stands for every project in the dependsOn. Writing project://docker-api in an inherited file would break the opt-out: moon would refuse the task of any API that removes the dependency.

3. Choosing the Dockerfile at build time

#!/usr/bin/env bash
# tools/docker-buildx.sh [buildx options] <context>
# Run from the project's directory: builds with its own Dockerfile
# if it has one, otherwise with the shared Dockerfile of its stack.
set -euo pipefail

root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
dockerfile="$root/${SHARED_DOCKERFILE:?missing shared Dockerfile}"
if [[ -f Dockerfile ]]; then
  dockerfile=Dockerfile
fi

echo "Dockerfile: $dockerfile" >&2
exec docker buildx build --file "$dockerfile" "$@"

The per-commit tag, the push and the digest are added as in our article on promotion by digest.

4. The shared Dockerfile

# infra/docker/api/Dockerfile
# The Dockerfile of every API. Build context: the API's directory, whose
# frankenphp/ folder keeps what differs from one API to another.
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"]

# ... PHP extensions, frankenphp_dev and frankenphp_prod stages ...

5. Checking with a probe commit

On a test branch, a commit changes only infra/docker/api/Dockerfile. The command MOON_BASE=main MOON_HEAD=HEAD moon query projects --affected --downstream deep --tasks docker-build must then list order, stock and shipping.

With the implicit input alone, the same test returns an empty list, while moon query tasks --affected lists the three docker-build tasks. We checked it with moon 2.4.5 and 2.6.5.

This probe commit is also the proof to require from a coding agent that changes a shared file.

6. Compose and the Dockerfile outside the context

In development, each API is built with Docker Compose, as in our note on FrankenPHP as non-root. Compose delegates its builds to Bake by default since its version 2.37.0 (5 June 2025), and always since 5.0.0 (2 December 2025).

Bake asks for a grant (--allow fs.read=...) to read a file outside its working directory. Before its version 5.7.0, Compose grants it for the context and the additional contexts of each service, not for the Dockerfile. From Buildx 0.21.0 to 0.37.1, Bake skipped this check with --progress rawjson, the mode Compose uses.

Since Buildx 0.37.2 (30 September 2026), that Compose therefore refuses a Dockerfile outside the context: additional privileges requested: pass "--allow=fs.read=...". Compose 5.7.0 (2 November 2026) also grants the read of the Dockerfile. For machines still on an earlier version, the Dockerfile's directory becomes an additional context, which Compose grants.

# services/order/compose.override.yaml
services:
  php:
    build:
      context: .
      # The shared Dockerfile of the APIs: an API that has its own removes
      # dockerfile and additional_contexts.
      dockerfile: ../../infra/docker/api/Dockerfile
      # Before Compose 5.7.0: lets Bake read the directory of the shared
      # Dockerfile. The Dockerfile never uses this context.
      additional_contexts:
        docker-api: ../../infra/docker/api
      target: frankenphp_dev

7. The shared Caddyfile and its fragments

# infra/caddy/spa/Caddyfile
# The Caddyfile of every Vue.js front. A front adds fragments to it
# (Caddyfile.d/global, site, extra) or replaces it with its own 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
}

An import whose glob finds no file is not an error, but Caddy writes a warning at every start. The fronts' Dockerfile therefore drops an empty fragment in each directory.

The shared Caddyfile reaches the image through a named context, caddy-config. docker-node.yml gives the fronts SHARED_DOCKERFILE: infra/docker/spa/Dockerfile and the --build-context caddy-config=$workspaceRoot/infra/caddy/spa argument. Each front lists caddy-spa and docker-spa in its dependsOn, as the APIs list docker-api.

# infra/docker/spa/Dockerfile
FROM caddy:2.11-alpine

# One empty fragment per import point: Caddy no longer warns about a glob with no file.
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

# The shared Caddyfile, then the front's fragments and its own Caddyfile,
# copied only if they exist.
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

A missing COPY source fails the build ("/Caddyfile.d": not found). A source that contains a pattern (*, ?, [...]) is handled differently: BuildKit accepts that it matches nothing, and copies nothing. Caddyfile.[d] only matches Caddyfile.d: it is an exact path, made optional.

The Dockerfile reference does not describe this behaviour. It comes from the code of the Dockerfile frontend (the AllowEmptyWildcard option), and we checked it with BuildKit 0.34.2. For a directory, COPY copies its contents, hence the /etc/caddy/Caddyfile.d/ destination.

8. Proving equivalence with caddy adapt

Before merging the migration, we compare the JSON that caddy adapt derives from a front's image, before and after. Our article on proving that a refactoring is equivalent details the recipe, and how to judge a difference.

Checklist

  • The shared file in its own directory, declared as a moon project with no task.
  • That project in the dependsOn of every user, and in the generator template.
  • Tasks that see their dependencies (project://^ or project://<id>).
  • A deployment query that follows dependents (--downstream).
  • A probe commit on the shared file alone, which lists all its users.
  • The project's Dockerfile preferred to the shared one, when it exists.
  • Compose 5.7.0 or later, or the Dockerfile's directory in additional_contexts.
  • Optional copies written with a bracket glob.
  • An adapted Caddy configuration identical before and after the migration.

Sources

Versions checked on 15 November 2026: moon 2.6.5, Docker Compose 5.7.1, Buildx 0.39.0, Dockerfile frontend 1.29.0 and Caddy 2.11.9.