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/*.ymlfile, adds the shared Dockerfile to the inputs of every inherited task.moon cithen reruns the tasks of the APIs when it changes. -
What it costs:
moon query projects --affecteddoes not read task inputs. A project is only affected by a changed file in its directory, or through itsdependsOnrelations. The deployment query still sees nothing.
Querying tasks instead of projects
-
What it solves:
moon query tasks --affectedtakes inputs into account. With the implicit input, it does list thedocker-buildtasks 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 thedocker-apiproject, with no task. Each API declares it in itsdependsOn. A change to the Dockerfile makesdocker-apiaffected, 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.
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 aheaderor aredir; -
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
dependsOnof every user, and in the generator template. -
Tasks that see their dependencies (
project://^orproject://<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.
-
moon, commands
query projects
and
query tasks:
--affected,--downstream,--upstream. -
moon,
project configuration:
id,dependsOn,layer,stackandproject://inputs. -
moon,
inherited tasks
(
implicitInputs), task inheritance (inheritedBy, merging ofargsandenv) and workspace (projects). - moon, affected tasks, variables and moon 1.29: tracking of affected projects and tasks.
-
moon, code of version 2.6.5:
affected projects,
query projects,
project:// inputs
and
layer constraints
(
invalid_layer_relationship, except across distinct stacks). -
Docker,
docker buildx build
(
--file,--build-context) and Dockerfile reference (COPY, patterns,--from). -
BuildKit,
Dockerfile frontend 1.29.0, COPY conversion:
AllowEmptyWildcard,CopyDirContentsOnly. -
Docker Compose,
build
(
dockerfile,additional_contexts) and versions 2.37.0, 5.0.0 and 5.7.0. - Docker Compose, issue 14285 and pull request 14325: read of the Dockerfile granted to Bake.
-
Docker Buildx,
docker buildx bake
(
--allow fs.read), version 0.37.2 and advisory GHSA-gwr2-q96m-6682. - Caddy, import, try_files, caddy adapt and import code: warning on a glob with no file.
- Lychen, pull request 271: an open-source implementation of the shared Dockerfile this article describes, in a moon monorepo.
- Lychen, pull request 272: the same approach applied to Caddyfiles, proposed in the same monorepo.