docker_compose_project
docker_compose_project brings the containers of one Docker Compose
project on the node to a state: running, stopped, or removed. A Compose
project is a file compose.yaml that declares several containers
("services") with their images, ports, mounts, and networks. The
docker compose command creates and updates the containers from it. The
module runs on the node and drives the docker command that is installed
there; MMX links no Docker library.
- docker_compose_project:
compose_project_name: shop
compose_project_dir: /opt/shop
state: running
pull_images: when_missing
containers_of_removed_services: remove
The Compose file and its environment files are ordinary file tasks, so
templates, secrets, differences in a dryrun, and check_new_file work as for
any file. MMX adds no container settings of its own: every setting is in the
Compose file, in Docker's own format. A value that differs for each node goes
into the file through template or content.
There is no module with one task for each container. One container is a
Compose project with one service; its file can be inline content, so it is
still one visible node task block. The other way to run a Docker container,
a systemd unit that runs docker run, gets its image from
docker_image.
Run containers
shows both ways and defines the words image, registry, tag, and
digest.
Set up
The Set up section also provides the setup instructions for
docker_image.
Install Docker and its Compose plugin first, with package tasks. MMX has no module that installs Docker. A complete node task list for a Debian or Ubuntu server that runs Docker:
- apt_repository:
name: docker
uris: ["https://download.docker.com/linux/{{ .node.distribution.id }}"]
suites: ["{{ .node.distribution.codename }}"]
components: [stable]
signing_key_url: https://download.docker.com/linux/debian/gpg
signing_key_sha256: 1500c1f56fa9e26b9b8f42452a553675796ade0807cdce11975eb98170b3a570
- apt_package:
packages:
- {name: docker-ce, version: "5:29.*"}
- apt_package:
packages:
- {name: docker-ce-cli, version: newest_when_first_installed}
- {name: containerd.io, version: newest_when_first_installed}
- {name: docker-compose-plugin, version: newest_when_first_installed}
- task_block:
id: docker_daemon
changes:
- file:
path: /etc/docker/daemon.json
permissions_mode: "0644"
content: |
{
"log-driver": "json-file",
"log-opts": {"max-size": "50m", "max-file": "3"},
"live-restore": true
}
activate:
- systemd_service:
name: docker
state: running
start_at_boot: true
refresh: restart
- user:
create_home_directory: true
name: deploy
supplementary_groups: [docker]
supplementary_groups_not_listed: keep
In order: the node gets Docker's package source, the Docker packages (the
daemon inside the version pattern 5:29.*), and the daemon's settings file.
Docker signs its Debian and its Ubuntu repository with the same key, so one
signing_key_url serves both; MMX fetches the key on the controller machine,
before it knows the node's distribution. The package does not start the daemon while
it installs; the systemd_service task starts it, and restarts it when
daemon.json changes. With "live-restore": true, Docker keeps containers
running during that restart. The account deploy joins the group docker,
which lets it use the docker command; anyone in that group has root on the
server, so add only administrators. To change how the packaged unit starts
the daemon, use a systemd_unit task with drop_in, never an edit of the
packaged unit.
The docker-host example is this list as a project, with the cleanup timer for unused images. A Compose project, such as the one in Run a Compose project, follows the Docker setup node tasks.
What each module needs. docker_image needs the docker command and a
Docker daemon that answers; docker_compose_project also needs the Compose
plugin. When the Docker command, an answering Docker daemon, or the required
Compose plugin is missing, the task fails as a
missing prerequisite,
which is not tried again. The message names the missing Docker command,
answering Docker daemon, or Compose plugin. A dryrun then reports the task
not checked. An earlier node task may install the Docker command or Compose
plugin, or start the Docker daemon.
Docker Compose 2.26.1 or newer. docker_compose_project requires Docker
Compose 2.26.1 or newer. With an older Compose the task fails with a message
that names the installed version and required version. With an older Docker
Compose version, a dryrun reports not_checked.
A version can carry a package's suffix (2.26.1-4,
2.40.3+ds1-0ubuntu1); MMX compares its leading numbers.
The Red Hat family. Docker publishes its repository for the Red Hat
family too (dnf_repository with
https://download.docker.com/linux/centos/$releasever/$basearch/stable; the
directories for Rocky Linux and AlmaLinux hold no engine). There the package
does not enable the daemon either, so the systemd_service task is needed
there too.
The Red Hat family 10 and the running kernel. Docker's firewall rules
need kernel modules, such as xt_addrtype, that the Red Hat family 10 ships
in the package kernel-modules-extra. Docker's packages bring that package,
but dnf installs it for the newest kernel in the repositories, together with
that kernel. A node that still runs an older kernel has no such modules
until it boots the new one, and Docker's daemon ends at every start with
iptables ... RULE_APPEND failed (No such file or directory). The
systemd_service task then fails and shows these journal lines. Put a
reboot node task between the package task and the systemd_service task,
or install the package for the running kernel first, with a dnf_package
task that names kernel-modules-extra-{{ .node.kernel.release }}.
Distribution packages of Compose. Debian 13's docker-compose (2.26.1,
with docker.io and docker-cli) and Ubuntu's docker-compose-v2 are
Compose version 2 or newer and work.
Debian 12 has no such package: its docker-compose is the old Python
program, which gives no docker compose command. Use Docker's repository
on Debian 12.
Inputs
compose_project_dir(string; required): absolute path of the directory on the node that holds the Compose file; relative paths inside the Compose file start in compose_project_dirstate(running,stopped,containers_removed_named_volumes_kept, orcontainers_and_named_volumes_removed; required): running runs docker compose up: creates missing containers, recreates containers whose definition or image differs, and starts stopped containers. stopped stops and keeps the containers. containers_removed_named_volumes_kept removes containers and networks, and keeps named volumes and volume data. containers_and_named_volumes_removed also deletes named volumes and volume data. No state deletes images, the Compose file, or directories on the node.pull_images(when_missingoralways; optional): required with state: running, no default; when_missing pulls an image only when the node does not have it; always asks the registry on every run which image each reference names now and recreates the containers whose image differscontainers_of_removed_services(removeorkeep; optional): required with state: running, no default; what happens to a container of this project whose service is no longer in the Compose filecompose_files(list of strings; default[compose.yaml]): relative paths inside compose_project_dir, including subdirectories, in Compose's order; a .. path that leaves the project directory is refusedcompose_project_name(string; required): required in every state. Use lowercase letters, digits, - and _, starting with a letter or digit. Give every Compose project a separate name. If another directory uses the requested project name, the node task fails and changes nothing.registry_logins(list of mappings; optional): only with state: running; a list of {registry, registry_username, registry_password} for private registries, used for this task's pulls and for a dryrun's question to the registry; registry is the registry's host as image references name it, with its port if they have one; registry_username and registry_password are private values, the password normally a secret; in a run they reach docker through a private directory under /run that the task removes, and a dryrun writes them nowhere; a secret in a login does not hide the task's result: MMX shows [redacted] wherever a text of the result holds the secret
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangereasonvalue.servicesvalue.images
What a dryrun reports
Changes nothing and writes no login; asks Docker Compose's own dry run (docker compose --dry-run up --no-start) what a run would do to each container; value.services lists for each service what a run would do (would_create, would_recreate, would_start, would_stop, would_remove, or unchanged) with the reason, which names both Compose versions when another Compose version made the container, or not_checked with the reason when the dryrun cannot tell: with pull_images: always, when an image's reference names a list of images for several platforms and the registry serves another list, the dryrun cannot see whether the image for the node's platform changed; the entry of such an image in value.images then has a reason too, unless the node's image store gives the image another ID for certain; the task reports would_change when something else is certain to change and not_checked otherwise; when an earlier node task of the same dryrun would change a file in compose_project_dir, or any file in the same task_block, every service reports would_change with a reason that says so; with pull_images: always it asks each registry without downloading, with the task's own logins only, and reports not_checked with the error when one does not answer; not_checked with the reason when Compose's dry run fails or prints a line that MMX does not know; a removal names the volumes that it would delete; not_checked while the docker command, the Compose plugin, the Docker daemon, or the Compose file is missing.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Run a Compose project
- task_block:
id: shop
changes:
- directory:
path: /opt/shop
permissions_mode: "0755"
- file:
path: /opt/shop/web.env
permissions_mode: "0600"
content: |
DATABASE_PASSWORD={{ .secrets.shop_database_password }}
- file:
path: /opt/shop/database.env
permissions_mode: "0600"
content: |
POSTGRES_PASSWORD={{ .secrets.shop_database_password }}
- file:
path: /opt/shop/compose.yaml
permissions_mode: "0644"
content: |
services:
web:
image: registry.example.com/shop/web:2.4
restart: unless-stopped
ports: ["127.0.0.1:8080:8080"]
env_file: [web.env]
healthcheck:
test: ["CMD", "curl", "--fail", "http://127.0.0.1:8080/health"]
depends_on:
database:
condition: service_healthy
database:
image: postgres:17.2
restart: unless-stopped
volumes: ["database_data:/var/lib/postgresql/data"]
env_file: [database.env]
healthcheck:
test: ["CMD", "pg_isready", "--username", "postgres"]
volumes:
database_data: {}
check_new_file:
shell:
script: >-
docker compose --project-directory /opt/shop
--file "$NEW_FILE" config --quiet
dryrun: >-
docker compose --project-directory /opt/shop
--file "$NEW_FILE" config --quiet
env:
NEW_FILE: "{{ .new_file.path }}"
activate:
- docker_compose_project:
compose_project_name: shop
compose_project_dir: /opt/shop
state: running
pull_images: when_missing
containers_of_removed_services: remove
verify:
- wait_for:
docker_compose_project_is_ready: /opt/shop
wait_at_most: 2m
On the node, in order: MMX creates the directory and writes the two
environment files. MMX writes the Compose file after docker compose config
accepted the new file; the environment files come first, because that check
reads them. Then docker_compose_project creates the two containers. Last,
wait_for waits until the web and database containers report healthy.
Two Compose features replace work that people otherwise script:
- Start order, also at boot. Use Compose's
restart:policy anddepends_onwithcondition: service_healthy, as in the example. Docker then starts the containers in the right order after a reboot without MMX. - A network or volume shared by two projects. Declare the shared network
or volume with a fixed
name:in the creating project's Compose file. Declare the shared resource asexternal: truein the using project's Compose file. Put the task for the project that creates the shared network or volume earlier in the node task list.
A changed file that is mounted into a container
A container has three kinds of input. At state: running, Compose notices
a changed container definition and a changed image. The third input is the
content of a file of the node that is mounted into a container, such as a
configuration file. Compose does not check the mounted file's content.
So the playbook says which service must reload or restart when the mounted
file's content changes:
- task_block:
id: shop_proxy_config
changes:
- file:
path: /opt/shop/proxy/nginx.conf
template: files/shop/nginx.conf.tmpl
permissions_mode: "0644"
activate:
- id: reload_shop_proxy
shell:
script: >-
docker compose --project-directory /opt/shop
exec --no-TTY proxy nginx -s reload
only_when_tracked_inputs_changed: true
/opt/shop/proxy/nginx.conf is a
tracked input of the node
task block shop_proxy_config: MMX remembers its hash. The shell
task reload_shop_proxy runs only when the hash of
/opt/shop/proxy/nginx.conf differs from the hash
recorded after the command last succeeded. If a run writes the file and
stops before the command, the next run finds the file unchanged and still
runs the command once
(execution design).
To restart the container instead, the script is
docker compose --project-directory /opt/shop restart proxy.
The author names the service and the action. MMX does not read the Compose
file to work out which containers mount which files. Put the
shop_proxy_config node task block after the block that runs
docker_compose_project, so that the container
exists when the command runs. On a run that writes the file for the first
time, the command runs once; a reload in a container that was just created
is harmless. On a node where the file was already in place, MMX stores the
record and does not run the command.
Mount the directory, not the single file. The Compose file of this
example mounts ./proxy:/etc/nginx/conf.d:ro. MMX replaces a file with a new
file of the same name. A container that mounts one file keeps the old file,
and a reload would read the old content. A container that mounts the
directory sees the new file.
The deploy-with-docker-compose example is a complete project with a mounted configuration file and a reload command.
Follow newer images and pull from a private registry
- docker_compose_project:
compose_project_name: shop
compose_project_dir: /opt/shop
state: running
pull_images: always
containers_of_removed_services: remove
registry_logins:
- registry: registry.example.com
registry_username: deploy
registry_password: "{{ .secrets.registry_password }}"
An image reference is the complete value of a service's image setting,
such as registry.example.com/shop/web:2.4. With pull_images: always, each
run asks the registry which image each reference in the Compose file names
now. The run pulls an image that differs from the node's and recreates the
containers of the pulled image. registry is the
registry's host as the image references name it, with its port if they have
one; docker.io is Docker Hub.
Newer images under the same tag
and logins for private registries
say what docker_compose_project and docker_image share: what a dryrun
asks the registry (on the docker_image page), and how a login reaches
Docker without a password on a command line or on a disk (in
Run containers).
Wait until a container is healthy
"Started" does not mean "working": a container with a restart policy shows as
running while its application ends again and again. A container's health
check is a command, declared with the container, that Docker runs again and
again to learn whether the application inside works. wait_for has two forms
that read what Docker learned:
verify:
- wait_for:
docker_compose_project_is_ready: /opt/shop
wait_at_most: 2m
verify:
- wait_for:
docker_container_is_healthy: audio-converter
wait_at_most: 2m
docker_container_is_healthy: <container name>waits until Docker reports that container healthy by the container's own health check. Thedocker_container_is_healthyform also serves a container that a systemd unit starts withdocker run, such as the one indocker_image's example. A container that declares no health check fails the task at once with a message that says so, because MMX would otherwise wait for an answer that never comes.docker_compose_project_is_ready: <project directory>waits until every container of that Compose project that declares a health check is healthy, and every other container of the project runs or has completed. A container has completed when it ended with exit code 0 and its restart policy does not start it again, as a service that runs once does, for example a database migration. A container that ended with another exit code, or that was stopped although its restart policy keeps it running, fails the wait. The wait finds the project's containers by the directory that Compose records as a label on each of them.
The docker_container_is_healthy and docker_compose_project_is_ready
forms use wait_at_most and the other rules of wait_for.
The two container wait forms change nothing, check once in a dryrun, and
belong in verify. When the wait ends without health, the task fails and
names each container that is not ready.
The failure reports each container's status. For a container with a health
check, the failure also reports the
last health check's exit code and output.
Stop a project for other work
Stop the containers for work that needs them stopped, such as a backup of their data directory, and start them again:
- docker_compose_project:
compose_project_name: shop
compose_project_dir: /opt/shop
state: stopped
- shell:
script: /usr/local/bin/back-up-shop-data
- docker_compose_project:
compose_project_name: shop
compose_project_dir: /opt/shop
state: running
pull_images: when_missing
containers_of_removed_services: remove
The playbook names the project, so there is no list of "the containers that
were running" to remember. When the backup fails, the run stops and the
project stays stopped; running the playbook again starts it, because the last
task declares the wanted state. To start the project again in the same
attempt, put the last task in the cleanup of a node task block.
Remove a project and keep its data
- docker_compose_project:
compose_project_name: shop
compose_project_dir: /opt/shop
state: containers_removed_named_volumes_kept
Deleting a docker_compose_project task from the playbook removes nothing on
the node, like every MMX task.
Remove a project and delete its data
- docker_compose_project:
compose_project_dir: /opt/shop
compose_project_name: shop
state: containers_and_named_volumes_removed
The task removes the containers and networks of the project shop in
/opt/shop and deletes its named volumes with the data in them. The
docker_compose_project task must name the project with
compose_project_name, because Docker records only the project's name on
a named volume, never the project's directory. MMX refuses a task without
compose_project_name when MMX loads the MMX project.
Give the Compose project name used by the project's other tasks.
For a project created outside MMX without an explicit name, Docker Compose
named the project after the last part of the directory's path, shop for
/opt/shop.
How it works
What each state does
The four states say what happens to the containers and to the data:
state |
What MMX does | What stays |
|---|---|---|
running |
Creates missing containers, recreates a container whose definition or image differs, starts stopped ones (docker compose up --detach). |
Everything. |
stopped |
Stops the project's containers (docker compose stop). |
The containers, their named volumes, the project's networks, the images. |
containers_removed_named_volumes_kept |
Stops and removes the project's containers and networks (docker compose down). |
The named volumes with their data, and the images. |
containers_and_named_volumes_removed |
Stops and removes the project's containers and networks, and deletes the project's named volumes with the data in them (docker compose down --volumes). |
The images. |
A named volume is a data directory that Docker creates and keeps for
containers, such as database_data above. A bind mount makes a file or
directory of the node visible inside a container. No state deletes a
directory of the node that is mounted into a container, the Compose file, or
an image. Remove a directory with a directory task and unused images with
the cleanup timer. The
three states other than running accept only compose_project_dir,
compose_files, and compose_project_name, and
every state requires compose_project_name
(why).
docker_compose_project normally stands in the activate phase of the node
task block whose changes write the project's files, as in
Run a Compose project. The docker_compose_project
module is also allowed as an ordinary node task. Health is not part of the
docker_compose_project task: a container that starts and
then fails its health check is a failed
wait_for in verify, never a
repeated start.
Which files Compose reads
MMX always names the files to docker compose: compose.yaml in
compose_project_dir, or the files of compose_files, which Compose
merges in their order, as docker compose --file does. Compose then neither
looks for a Compose file in the directories above nor adds a
compose.override.yaml that the task does not list. A file .env in the
project's directory still fills the ${...} references of the Compose file,
as Compose does by itself.
What a run does
A run with state: running always runs docker compose up, and Compose
decides what differs. Compose recreates a container when the service
definition's hash, including environment file values, differs from the hash
on the container. A different image also causes recreation. Depending on
the Docker Compose version, Compose also recreates or restarts dependent
services and restarts containers to replace a changed network.
MMX does not compute Compose's rules for recreating and restarting containers.
MMX reads the project's containers with docker container inspect before and after the command and reports each service's
action from the two states. MMX never reads the text that docker compose
prints while it works.
The task is tried again after a failure, so a registry that fails once does not fail the run.
MMX finds a project's containers by the directory that Compose records as a
label on each one. Before up, stop, or down, MMX lists the containers
that carry the project name the command will use; see
Two project directories with the same last name.
What a dryrun asks
A dryrun asks Docker Compose for that decision: MMX runs Compose's own dry
run, docker compose --dry-run --progress plain up --no-start --pull never,
with --remove-orphans when the task removes the containers of removed
services. Compose then lists what it would do to each container, one line of
text for each step, such as Container shop-web-1 Recreate, and changes
nothing. So a dryrun says what the Compose version on the node would do. MMX
maps the steps to the services' actions:
| Compose lists for a container | The service's action |
|---|---|
Recreate |
would_recreate |
Creating, for a container that does not exist yet |
would_create |
Removing |
would_remove |
Stopping without Removing: Compose stops the container and starts it again |
would_start |
Running |
unchanged |
nothing, or Created, for a container that does not run |
would_start |
MMX reads the lines with a closed list of words. A line that MMX does not
know, a container that the lines do not account for, or a dry run that fails
makes the task not_checked with the reason. MMX never guesses, so a later
Compose that prints something else is not read as a wrong prediction.
--no-startasks for the creation step alone, which decides what happens to each container. What the start step adds, MMX sees itself:upstarts each container that does not run.- Compose 2 prepares its build tool, buildx, also in a dry run, and creates
that tool's state files in Docker's configuration directory, which is in
the home directory of the account executing the node task. MMX sets
BUILDX_CONFIGto the node task's private directory in/run/mmx/private_task_directories/for the command and removes the directory after it. The dry run then leaves nothing on the node. Compose 5 writes no file. --pull neverkeeps Compose's dry run away from the registries. Which images a run would pull, MMX works out itself: an image that the node does not have and, withpull_images: always, one for which the registry names another image now. A service whose image the registry has replaced reportswould_recreatewith the reasonthe image differs.
When a dryrun cannot tell
The task reports not_checked with the reason, and never a guess, in these
cases:
- Compose's dry run fails. The reason holds Compose's message.
- Compose's dry run prints a line that MMX does not know. A service that
Compose builds on the node (
build:) while its image is missing is such a case. - The node no longer has the image of a container, and the Compose file still names that image. Compose's dry run would recreate the container. A run pulls the image first, and Compose keeps the container only if the image is the one it was created from.
- With
pull_images: always, the registry serves another list of images for several platforms than the node's image came from; thedocker_imagepage's newer images under the same tag says why.
A run is not affected: it runs docker compose up and reports what changed.
What the result holds
value.services holds one entry for each service with name and action.
In a run, the action is created, recreated, started, stopped,
removed, or unchanged. In a dryrun, the service's action says what a run
would do:
would_create, would_recreate, would_start, would_stop,
would_remove, unchanged, would_change when the service changes and MMX
cannot say how, or not_checked when MMX cannot tell whether it changes.
The task reports changed when an action is not unchanged or an image was
pulled. value.images lists each image that was pulled, with image,
previous_image_id (null when the node did not have the image), and
image_id.
In a dryrun, each service that would change has a reason beside its action:
the container is missing, the definition differs, the image differs,
the container is stopped, the service is no longer in the Compose file,
or that Compose stops and starts it for a service it depends on. When an
earlier node task of the same dryrun would change a file in
compose_project_dir, or any file in the same node task block (it may
be an environment file that a service reads), MMX shows that task's
difference, and every service reports the action would_change with the
reason an earlier node task of this dryrun would change a file of this Compose project or of this node task block: the services can be compared
with the containers only once the files are installed.
An unchanged rerun: docker compose up finds nothing to do, every service is
unchanged, and the task reports unchanged.
After an interrupted run
The state lives in Docker, not in an MMX record. A run that wrote the Compose file and stopped before the containers were updated is finished by the next run: the running containers still carry the old hash, so Compose recreates them then.
A project that already runs
A project that someone created and started with docker compose up needs no
preparation. MMX keeps no record of its own about a project and reads
Compose's labels only to find a project's containers and their services. The
state is the containers, and Compose compares them with the Compose file. The
first dryrun shows what the first run would do. When the files on the node
are the ones the containers were created from, that is nothing, and the run
keeps the same containers.
Two project directories with the same last name
Supply compose_project_name in every docker_compose_project task, in
every state. Give each project
its own name, even when /opt/shop/app and /opt/blog/app have the same
last directory name. MMX checks before each command whether another directory
has containers with the current task's compose_project_name. A shared
name fails as a configuration error
and changes nothing.
Docker records only a project's name on its named volumes. MMX cannot infer which directory owns a volume when no container remains. MMX can discover named volumes for removal only while it can load the project's Compose files or find its containers; the project name alone does not find volumes after both are gone. Two directories given the same Compose project name remain one project to Compose.
Services that change together with others
- A service that depends on a changed one. When Compose recreates a
service, it also acts on a service that depends on it with
restart: true. Compose 2.26 recreates the dependent service too. Later versions stop and start the dependent service, and the task reports the dependent servicestarted. A dryrun predicts what the node's version does. - A changed network or volume definition. Current Compose versions (2.35
and later in MMX's tests) replace a network whose definition in the
Compose file changed: they stop the project's containers, replace the
network, and start the containers again. The task reports the services
whose containers restarted
started. A dryrun predicts the container restarts needed to replace the network. Compose 2.26 keeps the network as it is. No Compose version replaces a named volume that exists, because its data would be lost: newer versions ask first, and MMX never answers. To apply a changed volume definition, back up the data, remove the project withcontainers_and_named_volumes_removed, and run the playbook again. - After an upgrade of Compose. Two Compose versions can give the same
definition different hashes; 2.40 and 5.6 do. After such an upgrade,
docker compose uprecreates every container once, and so does the task. A dryrun says why: the service'sreasonnames the Compose version that made the container and the one the node has now. - An image for several platforms. In Docker's containerd image store, the ID of such an image changes when the image of any platform changes. Docker Compose 5 keeps a container whose image for its own platform stayed the same, and MMX then reports the service unchanged too.
- A service that ends by itself. A service that runs once and ends, such
as a database migration, is not running at the next run. Compose starts
the service that runs once again with every
docker compose up. So the task reports the service that runs oncestartedand changed on every run. - Services with several containers. A service with
deploy.replicasorscaleis unchanged when it has that many containers and Compose keeps each one. When Compose increases a service's container count, the task reports the servicecreated. When Compose decreases the container count, the task reports the serviceremoved. - Containers that
docker compose runstarted. Containers started bydocker compose runbelong to no service's set. Therunningstate leaves containers started bydocker compose runalone. Thestopped,containers_removed_named_volumes_kept, andcontainers_and_named_volumes_removedstates stop or remove containers started bydocker compose runwith the project.
Removal
A removal that is run again reports unchanged: the three states other than
running are satisfied when the project has no containers. Because MMX finds
the project's containers by the directory that Compose records on each of
them, this also holds after the Compose file, the directory, or Docker
itself is gone, and containers that are left when the directory is gone, or
whose service has left the Compose file, are still stopped or removed with
the others.
Which named volumes go. containers_and_named_volumes_removed deletes
the named volumes that the Compose file declares. A dryrun lists the
declared named volumes to delete in the task's reason. A run lists the
declared named volumes deleted. The task also removes and lists declared
named volumes after containers were removed earlier, as long as Compose can
load the Compose file. A volume that the Compose file marks external: true is
never deleted.
A Compose file that is gone or that Compose cannot load. A removal does
not need the project's files. When the Compose file is gone, or Compose
cannot load it, for example because an environment file that it names was
deleted first or a run stopped halfway, MMX removes the project by the name
that its containers carry, and the reason says that the files could not be
loaded. The volumes that go are then those that Compose labelled with the
project's name when it created them, and the dryrun and the run name them
too. Without loadable files and without containers, MMX cannot know the
project's volumes and reports unchanged.
Errors and what they mean
Every reason starts with docker_compose_project.
| The reason holds | What the reason means, and what to do |
|---|---|
the program docker is not installed; install Docker in an earlier node task |
Docker is not on the node. Install Docker in an earlier node task. See Set up. The failed docker_compose_project task is not tried again. A dryrun reports the docker_compose_project task not_checked. |
the Docker Compose plugin is not installed (the docker command has no compose command) |
The node has the docker command but no Compose plugin. Install the Docker Compose plugin in an earlier node task, for example the package docker-compose-plugin. |
the Docker daemon does not answer (...) |
The daemon is not installed, not started, or does not answer. Start it in an earlier node task, for example with systemd_service and name: docker. On the Red Hat family 10, read the running kernel in Set up. |
Docker Compose 2.24.0 is installed, and MMX needs Docker Compose 2.26.1 or newer |
Install a newer Compose plugin in an earlier node task. |
the Compose file /opt/shop/compose.yaml does not exist; an earlier node task, such as a file task, may create it |
Write the Compose file with a file task before the docker_compose_project task. |
the project of /opt/shop/app and the project of /opt/blog/app have the same project name, app |
Two project directories have one project name. MMX changed nothing, and the task is not tried again. Give each project its own compose_project_name. |
state: stopped accepts only compose_project_dir, compose_files, and compose_project_name; remove pull_images |
A state other than running has a field that only running uses. MMX rejects the MMX project during loading. Remove the field named in the error. |
compose_project_name is required in every state |
Add the unique Compose project name used by every task managing the Compose project of the failing task. MMX never infers the Compose project name from a directory. |
state: running needs pull_images: when_missing or always and state: running needs containers_of_removed_services: remove or keep |
The pull_images and containers_of_removed_services fields have no defaults. Supply the required field named in the error message. |
In a dryrun: MMX cannot tell what a run would do, because Docker Compose's own dry run failed: ... or ... printed a line that MMX does not know: ... |
The task is not_checked. A run is not affected. See When a dryrun cannot tell. |
In a dryrun: MMX cannot tell whether a run recreates the containers of service web: the node no longer has their image ... |
The node no longer has the image of a container; only the run's pull can tell. |
From wait_for: the container ... declares no health check, so Docker never reports it healthy |
Declare a health check in the image, the docker run command, or the Compose file, or wait for a port or a url instead. |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/docker_containers.py runs in a virtual machine
on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10. The suite covers docker_compose_project,
docker_image, and the wait_for forms docker_container_is_healthy and
docker_compose_project_is_ready:
| Distribution | Docker | Docker Compose | Source of Docker and Docker Compose packages | Image store |
|---|---|---|---|---|
| Debian 12 | 29.9 | 5.6.0 | Docker's repository | containerd |
| Debian 13 | 26.1.5 | 2.26.1 | Debian's own packages | classic |
| Ubuntu 24.04 | 29.9 | 5.6.0 | Docker's repository | containerd |
| Ubuntu 26.04 | 29.1.3 | 2.40.3 | Ubuntu's own packages | not recorded |
| Rocky Linux 9 | 29.9 | 5.6 and 5.7 | Docker's repository | containerd |
| AlmaLinux 10 | 29.9 | 5.6 and 5.7 | Docker's repository | containerd |
The suite also passed on Hetzner Cloud servers with Debian 13.
Not verified in a suite: Docker Compose between 2.26.1 and 2.40.3 and from 5.0 to 5.5; the form of their dry run's lines was measured by hand on ten versions. Pulling an image from a public registry with a separate authentication service, such as Docker Hub or GitHub's registry, is also not verified in a suite. The suite pulls from a test image registry on the guest.
Why it works this way
-
The Compose file is the declared thing. The Compose file already has every container setting, and Compose already compares a container with its definition correctly. A module with container settings of MMX's own would duplicate Compose's settings and container comparison, and miss settings.
-
Docker and Podman have separate modules. They work differently on the server: Docker has a daemon and Compose, Podman has systemd units. A shared name would hide whether Docker or Podman runs. Podman's containers are written with
podman_quadlet. -
pull_imageshas no default. The choice decides whether a rerun deploys new software, so it must be on the page. A moved tag is a change outside the project, like a moved Git branch;alwayson the task is where a reader sees that the task follows it. -
containers_of_removed_serviceshas no default.removedeletes a container,keepleaves one running that the Compose file no longer describes. Theremoveandkeepchoices are unsafe to assume as defaults. -
The removal states say whether data stays. A reader must see from the one line
state: containers_and_named_volumes_removedthat data is deleted. -
Every state requires
compose_project_name. Directory names can collide, and Docker records no directory on a named volume. An explicit project name prevents a hidden guess about container and volume ownership, following required settings. -
compose_filesaccepts relative paths inside the project directory. Splitting Compose definitions into subdirectories is ordinary use. A..path that leaves the directory is refused because the task names one project directory. -
The entries of
registry_loginsareregistry,registry_username, andregistry_password. The linepassword: "{{ ... }}"alone does not say whose password it is, and the image modules already sayregistry_usernameandregistry_password. -
A changed mounted file is followed by a command the author writes. MMX does not read the Compose file to work out which container mounts which file. The reader sees which container reloads and why, and one mechanism, the command record, remembers what follows a change.
-
Health is a
wait_forinverify. A failed health check must not repeat or hide a start that succeeded. The task that starts the containers reports what it did to them; the wait reports whether the application works. -
docker_compose_project_is_readycounts a container without a health check as ready when it runs, or when it ended with exit code 0 and its restart policy does not start it again. A service that runs once and ends, such as a database migration, is normal in a Compose project; without this rule such a project could never pass the wait. The limit: a long-running service without a health check and without a restart policy that ends with exit code 0 counts as completed too, so such a service needs a health check or a restart policy. -
The task fails when a container that carries its project name belongs to another directory. Two directories with the same last part would otherwise remove each other's containers and volumes, and the result would name only the services of the task's intended Compose project.
-
A removal does not depend on Compose files that load. A removal playbook that deleted an environment file first, or a run that stopped halfway, must not block the removal; and no volume may be deleted without being named.
-
After a
docker ... inspectthat fails, MMX asks the daemon for its version before it takes "not found" for the answer. The faileddocker ... inspectcommand returns failure for a missing resource and for a daemon that does not answer. Only the inspect command's error text distinguishes a missing resource from an unavailable daemon. A daemon that stopped between two commands must not turn a removal into "unchanged". -
A dryrun asks Compose's own dry run. Only Compose knows its rule for recreating a container: a hash of the service's definition with the values of its environment files, the image, the services it depends on, and its networks, and the rule differs between versions. MMX's own comparison was wrong where it matters most. For a service with
env_file,docker compose config --hashprints a different hash from the hashupstores on the container. The hash difference was measured on Compose 2.23.3 to 2.40.3 and on 5.0.0 and 5.1.0.MMX's own comparison therefore predicted recreation for an existing project newly managed by MMX, although a run changed nothing. MMX's own comparison also missed Compose 2.26 recreating dependent services together with changed dependencies. The comparison also missed later Compose versions replacing changed networks. For adopted projects, dependent services, and changed networks, Compose's dry run matched the run on 2.26.1, 2.29.7, 2.35.1, 2.40.3, and 5.6.0.
-
Reading the dry run's text is safe. Reading Compose's dryrun text is an exception to "never read a tool's progress text", for three reasons. The dry run is Compose's documented mode that changes nothing. In about 200 measured dry runs, no container, image, network, or volume changed. The only files written were buildx state files on Compose 2. MMX directs the buildx files to a private directory under
/run, then removes the directory.Text is the only Compose dryrun output format available across all supported versions. The
--progress jsonoption exists from 2.29.0, not on 2.26.1, and the JSON fields changed with 5.0.0. And a line that MMX does not know, or a container that the lines do not account for, makes the tasknot_checked, never a prediction. -
--no-startand--pull never. The start step of a dry run waits for the real containers that a service depends on: on Compose 2 it never returns when a service must complete first (condition: service_completed_successfully) and its container is new, and it fails while such a container is unhealthy. And the dry run treats each image that it pulls as another image and would recreate each container. -
A dryrun's actions are
would_create,would_recreate, and so on.action: recreatedin a dryrun reads as done. -
Docker Compose 2.26.1 or newer. Docker Compose 2.26.1 is the lowest version that a supported distribution packages (Debian 13's
docker-compose). Docker Compose 2.26.1 is also the lowest version MMX is tested with. Older versions have faults that break the module's promises.Compose 2.8.0 to 2.12.2 leave the image label off a container when
upitself pulled the image. Then the nextuprecreates the container, so a rerun is not unchanged. Before Compose 2.8.0,uphas no--pulloption to apply the task'spull_imageschoice. -
No module installs Docker. A module that installed Docker would hide five existing node tasks behind a name. The list in Set up shows the five Docker setup node tasks, and each stays visible: the package source, the version pattern, the daemon's settings.
This page is docs/reference/modules/docker_compose_project.md in the MMX repository.