Compose v2 architecture — the plugin, the project model · Docker & Containers

Compose is a declarative format for multi-container applications. A compose.yml file describes services, networks, volumes, configs and secrets. The docker compose CLI applies that description to the local daemon.

That is the whole of it, and the word to hold onto is applies. Compose has no runtime of its own. It reads YAML, works out the difference between what the file says and what the daemon already has, and issues the same API calls you would issue by hand. Everything surprising about Compose comes from how it decides which existing objects belong to your file.

Compose v2 is a CLI plugin

Compose v2 is a plugin (docker compose) shipped with the Docker CLI. It is not a separate binary you install and it is not the Python docker-compose of v1, which reached end of life in July 2023.

Read-only / Safeversion— Confirm which Compose is answering, and where it lives.

$ docker compose version && docker info --format '{{range .ClientInfo.Plugins}}{{.Name}} {{.Version}} {{.Path}}{{println}}{{end}}'

Docker Compose version v2.35.1
buildx v0.23.0 /usr/libexec/docker/cli-plugins/docker-buildx
compose v2.35.1 /usr/libexec/docker/cli-plugins/docker-compose

Illustrative output

Two practical consequences. First, docker-compose with a hyphen may still exist on the host as a shim or a leftover v1 install, and the two can disagree about project naming rules — always type the space. Second, because Compose is a client-side plugin, DOCKER_HOST applies to it: pointing that variable at a remote daemon or an SSH endpoint makes docker compose up deploy there, which is either exactly what you wanted or the reason a stack appeared on the wrong host.

The file format is governed by the Compose Specification, an open standard that other tools also implement.

The project model

A Compose project is a set of services plus a project name. That name is not decoration: it is the key Compose uses to find the containers, networks and volumes it already owns.

Project name resolution, and the labels it writes

Compose picks the project name from the first of these that is set:

-p / --project-name on the command line
COMPOSE_PROJECT_NAME in the environment
The top-level name: key in the Compose file
The base name of the project directory
The base name of the current directory, if Compose was invoked with -f and no other signal

The result is normalised: lowercased, with anything outside [a-z0-9_-] stripped. This matters more than it sounds. A directory named My App and a directory named myapp both resolve to myapp.

Compose then stamps that name onto every object it creates, as labels the daemon stores and you can read back:

com.docker.compose.project — the project name
com.docker.compose.service — the service name within the project
com.docker.compose.container-number — the replica index
com.docker.compose.project.working_dir — where it was run from
com.docker.compose.project.config_files — which files were merged
com.docker.compose.config-hash — a hash of the resolved service configuration, which is how up decides whether a container needs replacing

There is no state file. docker compose ps is a label query against the daemon, which is why it works from any directory as long as you supply the same project name, and why deleting your Compose file does not orphan the stack — the daemon still holds the labels.

Read-only / Safelabel query— Ask the daemon what Compose actually owns, without a Compose file.

PROJECT=myapp

docker ps -a --filter "label=com.docker.compose.project=$PROJECT" \
--format 'table {{.Names}}\t{{.Label "com.docker.compose.service"}}\t{{.Status}}'

# Every project the daemon knows about, including ones with no file left
docker compose ls --all

Each project gets its own network by default, named <project>_default, and containers within a project resolve each other by service name through the daemon’s embedded DNS resolver at 127.0.0.11.

Two stacks, one directory name, one network

The failure this causes is quiet and takes a long time to spot. Two unrelated deployments, checked out on the same host:

/srv/customer-a/app/compose.yml
/srv/customer-b/app/compose.yml

Both directories are named app. Both projects are therefore named app. Both stacks join the network app_default, both containers are called app-api-1, and the second docker compose up -d does not create a second stack — it adopts and reconfigures the first one, because as far as Compose is concerned those containers already belong to project app and merely have the wrong config hash.

Customer A’s API is stopped, removed, and recreated from Customer B’s file. If the two use the same service names and different images, the symptom is that Customer A is suddenly running the wrong version. If they use different service names, the symptom is that Customer A’s containers survive but appear as orphans — and the next docker compose up --remove-orphans in directory B deletes them.

Even without a name collision on the containers, a shared app_default network is a security problem in its own right: Customer A’s database is resolvable by name from Customer B’s application container, because Docker’s embedded DNS serves every container on the network.

The fix is one line at the top of every Compose file you deploy:

name: customer-a-app
services:
  api:
    image: myorg/api:1.4.0

The top-level name: travels with the file, survives being moved, and does not depend on anybody remembering to type -p.

What Compose does

Creates networks, volumes, configs and secrets as declared.
Creates and starts containers in dependency order.
Reconciles the running stack against the file on each up, replacing only the containers whose config hash changed.
Tears down the project with down.
Merges override files, resolves .env interpolation, selects profiles, and scales services.

What Compose does not do

Schedule across hosts. Compose is a single-host tool.
Self-heal across host failure. Restart policies are per-container and the daemon has to be alive to apply them.
Roll deployments. up replaces containers; it does not shift traffic.
Replace Kubernetes or Swarm. Those are orchestrators.

For multi-host deployments, Compose can be the front end (define the application) and an orchestrator the back end (run it). Tools like Kompose translate a Compose file into Kubernetes manifests.

What if you run docker compose from the wrong directory?

Nothing warns you. Compose derives a project name from wherever you are, finds no containers with that label, and cheerfully builds a second complete copy of your stack — new containers, a new network, and new named volumes, because the volume db-data in project staging is a distinct daemon object called staging_db-data from the prod_db-data that holds your data.

The symptom is an empty database and a confident operator, because docker compose ps in the new directory shows a healthy stack. The diagnostic is docker compose ls --all, which lists every project the daemon knows about along with the config files each one was created from:

NAME      STATUS       CONFIG FILES
prod      running(5)   /srv/prod/compose.yml
staging   running(5)   /srv/staging/compose.yml

Two projects where you expected one is the answer. To act on the right one from anywhere, name it explicitly: docker compose -p prod ps.

Compose v2 is a CLI plugin

The project model

What Compose does

What Compose does not do

Knowledge check