docker compose

The heart of Docker Compose is the Compose file: a YAML file containing services, networks, volumes, and configurations. This file is usually named `compose.yaml` or `docker-compose.yml`. Services are described with attributes such as the Docker image, build instructions, port mappings, environment variables, dependencies, and volume mounts. This declarative approach makes infrastructure reproducible and versionable — infrastructure as code.

The Compose CLI: v2 and v5

The Compose CLI is the command-line interface for Docker Compose. The currently supported versions are Compose v2 and v5. These are included with Docker Desktop and are available for Linux.

Since Compose v2, the invocation has changed from `docker-compose` (with a hyphen) to `docker compose` (without a hyphen). It is now a subcommand of `docker`. This change integrates Compose more smoothly with Docker Engine and ensures a consistent user experience.

Since Compose v2, the tool ignores the top-level `version` field in the Compose file. Previously, you had to specify `version: '3.8'` to indicate the format. Now Compose relies on the Compose Specification — a common standard maintained by the open source community and Docker. This spec makes the Compose file format uniform, independent of the user application or environment. As long as you adhere to the specification, you don't need to worry about compatibility between Compose versions.

History and versions

Docker Compose dates back to 2014, when Compose v1 was released. This first version simplified developing complex multi-container applications. v1 was widely adopted but had limitations: poor integration with Docker Engine and limited functionality when managing stacks in swarm mode.

In 2020, Docker announced Compose v2 — a complete rewrite in Go. This version offers better performance, better error handling, and tighter integration with the Docker platform.

Support for Compose v1 ended after June 2023. From that point, v1 was removed from future versions of Docker Desktop. The transition to v2 was necessary to reduce technical debt and accelerate the development of new features within a more modern codebase.

Compose v2 added functionality that gives developers more control. `ssh` agent forwarding for securely building images came in Compose v2.4.0 GA. This allows you to clone private Git repositories during the build process without copying SSH keys into the container.

Platform specification in the build section came in Compose v2.11.0. This explicitly specifies on which CPU architecture an image should be built — `linux/amd64` or `linux/arm64` — relevant when developing on Apple Silicon (M1/M2) Macs or multi-architecture deployment.

Development remains active. According to the official GitHub repository, there have been 284 releases to date. The most recent version, v5.5.0, was released on August 17, 2026. Docker Compose remains a core part of the Docker ecosystem.

On August 31, 2021, the Compose CLI code was officially moved to the `docker/compose/v2` repository. This migration marked the end of the old codebase and the beginning of a new development line. The code is open source under the MIT license.

Working with Docker Compose

Step 1: Create a project folder and a Compose file

Create a folder for your project and a `compose.yaml` file:

mkdir myapp && cd myapp && touch compose.yaml

Step 2: Define the services

Open `compose.yaml` in your editor and define the services. An example with PostgreSQL, Redis, and Nginx:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - db-data:/var/lib/postgresql/data
  redis:
    image: redis:7
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
    depends_on:
      - db
      - redis</p><p>volumes:
  db-data:

Step 3: Start the stack

Start all services with one command:

docker compose up -d

`-d` runs the containers in the background (detached mode).

Step 4: View the status

Check whether all services are running:

docker compose ps

Step 5: View logs

View the logs of a specific service:

docker compose logs web

Step 6: Stop the stack

Stop all services:

docker compose down

Step 7: Build images with platform specification

Build an image for a specific platform:

docker compose build --platform linux/arm64

Step 8: Use `docker stack deploy` for swarm mode

Deploy a stack based on a Compose file in swarm mode:

docker stack deploy --compose-file compose.yaml mystack

Verification

Check that the stack is running correctly:

docker compose ps

The output shows each service with status `Up` or `running`. Also check that the services are reachable on the expected ports:

curl http://localhost:8080

For a stateless stack with PostgreSQL, Redis and Nginx, an HTTP response from Nginx confirms that the stack is working.

Common problems

1. `docker compose` does not work

Cause: Compose v1 is being used or Compose is not installed. Solution: Use `docker-compose` (with a hyphen) for v1, or install Compose v2. Check the version:

docker compose version

2. Error: `version` is ignored

Cause: Compose v2 ignores the `version` field. Solution: Remove the `version` field from `compose.yaml`. Follow the Compose Specification.

3. SSH-agent forwarding does not work

Cause: The SSH-agent has not been started or the key is not loaded. Solution: Start the agent and load the key:

eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519

Related tools

`docker stack config` shows the final contents of a Compose file after merging and interpolating variables. Useful for debugging and validating complex configurations.

Whaler is a Linux program for Docker container management. It starts and stops standalone containers and Docker Compose applications, views logs, and offers a simple interface for basic actions. Developed by Selivestrov Dmitriy, licensed under GPL-3.0+, installable via Flatpak.

Deprecated versions

Older versions of the Compose file format — v1 and v2.x — are no longer actively maintained. The documentation for these has been moved to the V1 branch of the Compose repository on GitHub. The Compose Specification has been the standard since Compose 1.27.0+.

Docker Compose unifies complex multi-service applications in a YAML file, enables developers to iterate quickly, and ensures consistency between development, testing, and production environments. With an active development cycle, strong integration with Docker, and a clear migration path away from deprecated versions, Docker Compose remains a reliable choice for containerized workloads. The question is not whether you use Compose, but when you will make the switch to v5.