Opscraft
Docker Compose · Lesson 1 of 10 · 3 min read

What Compose is and how it organises things

Docker Compose describes a multi-container application — services, networks, volumes, secrets — in one YAML file and runs it with one command on a single Docker host. It's the standard for local development environments and for spinning up real dependencies (databases, queues, caches) in CI integration tests. Interviewers use it to check that you understand service discovery, startup ordering and health, environment configuration, and when Compose stops being the right tool.

Compose V2 and the Compose Specification

  • Compose V1 was a separate Python tool, docker-compose. It's end-of-life.
  • Compose V2 is a Go plugin built into the Docker CLI: docker compose (space, not hyphen).
  • Files follow the open Compose Specification. The old top-level version: "3.8" key is obsolete — V2 ignores it (and warns). Don't confuse Compose file "v3" with Compose V2.
Enlarge diagramcompose.yamlservices, networks,volumesdocker compose upapia containerdba container + volumeredisa containernetworkshop_default
Figure 1. Compose describes a whole multi-container app in one file and creates everything with one command.
Swipe sideways to see all of it, or tap to open it full screen.

File discovery

docker compose looks in the current directory (then parents) for compose.yaml, compose.yml, docker-compose.yaml or docker-compose.yml. It also loads compose.override.yaml automatically if present. Point at specific files with -f (repeatable).

The project

Everything Compose creates belongs to a project. The project name defaults to the directory name; override it with -p, the COMPOSE_PROJECT_NAME variable, or a top-level name: key. Resources are named after it:

Enlarge diagramproject "shop"folder name, -p, orname:networkshop_defaultvolumeshop_pgdatacontainersshop-api-1, shop-db-1, shop-worker-1
Figure 2. Everything Compose creates is named after the project, which defaults to the folder name. Two checkouts in folders with the same name collide.
Swipe sideways to see all of it, or tap to open it full screen.

Compose finds its containers again through labels (com.docker.compose.project, com.docker.compose.service). Two checkouts of the same repo in directories with the same name will collide; give each a distinct project name. CI pipelines running in parallel on one host should always set a unique project name (e.g. include the build number).

Top-level sections

name: shop
services:   { ... }   # containers to run
networks:   { ... }   # custom networks
volumes:    { ... }   # named volumes
secrets:    { ... }   # files mounted at /run/secrets/<name>
configs:    { ... }   # non-sensitive config files