docker compose (file)
The compose.yaml format — services, images, ports, variables, volumes, networks, depends_on and healthcheck
A Compose file (compose.yaml or docker-compose.yml) describes several containers that run together: which image to use, which ports to open, which variables and volumes to attach, in what order to start. docker compose up reads the file and brings up everything it describes.
Docker is not installed in the sandbox. Here you can write and check the file itself: yamlschema compose file validates it against the Compose Specification schema and prints the errors.
Syntax
services:
service_name:
image: image:tag
key: value
volumes:
volume_name:
networks:
network_name:
By default all services in the file join a shared network, and the service name serves as a DNS name: service app reaches service db at the address db. The version: key at the top of the file is obsolete and ignored.
Top level
| Key | What it defines |
|---|---|
services | containers — the main part of the file |
volumes | named volumes (data survives container re-creation) |
networks | networks; without them a single default network is created |
secrets / configs | files mounted into containers (/run/secrets/name) |
name | project name (prefix for containers, volumes, networks) |
Service keys
Image and startup
| Key | What it defines |
|---|---|
image | the image, e.g. postgres:16 |
build | build the image: build: . or context, dockerfile, args, target |
command | override the image's command (CMD); as a string or a list |
entrypoint | override the image's ENTRYPOINT |
container_name | a fixed container name (then the service can't be scaled) |
user, working_dir | the process's user and working directory |
restart | no (default), always, on-failure, unless-stopped |
profiles | the service starts only if the profile is enabled: --profile name |
init | run a tiny init process that reaps zombies and forwards signals |
Network and ports
| Key | What it defines |
|---|---|
ports | publish to the host: "8080:80", "127.0.0.1:8080:80" (local only), "53:53/udp" |
expose | the port is visible to other services but not to the host (serves as documentation) |
networks | which networks to attach the service to |
extra_hosts | extra entries in the container's /etc/hosts |
Variables and data
| Key | What it defines |
|---|---|
environment | variables: as a mapping KEY: value or a list - KEY=value |
env_file | a file (or list of files) with KEY=value lines |
volumes | volume_name:/path — a volume; ./dir:/path — a host directory; :ro — read-only |
tmpfs | in-memory directories |
secrets | which top-level secrets to attach |
Order and health
| Key | What it defines |
|---|---|
depends_on: [db] | short form: start after the db container |
depends_on: {db: {condition: …}} | long form with a condition (see below) |
healthcheck.test | the check command: ["CMD", "prog", "arg"] or ["CMD-SHELL", "string for sh"] |
healthcheck.interval / timeout / retries | how often to check / how long to wait for a response / how many failures in a row mean "unhealthy" |
healthcheck.start_period | startup time during which failures don't count yet |
deploy.resources.limits | cpus and memory limits |
logging | log driver and its options (max-size) |
Conditions in depends_on:
condition | Wait until the dependency… |
|---|---|
service_started | has started (same as the short form) |
service_healthy | becomes healthy — the dependency needs a healthcheck |
service_completed_successfully | exits with code 0 (migrations, data preparation) |
Variable substitution
Values can reference environment variables and the .env file next to the compose file: ${TAG}, ${TAG:-latest} — a default value, ${TAG:?TAG must be set} — an error if the variable is missing. $$ is a literal $.
Commands (where Docker is installed)
| Command | What it does |
|---|---|
docker compose up -d | create and start everything in the background; --build — rebuild images |
docker compose down | stop and remove containers and networks; -v — volumes too |
docker compose ps | service status |
docker compose logs -f service | logs, waiting for new ones |
docker compose exec service sh | a shell in a running container |
docker compose run --rm service command | a one-off container of the service |
docker compose config | the final file after variable substitution and validation |
docker compose restart / stop / pull / build | restart / stop / pull / build images |
Examples
services:
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: example
volumes:
- db-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 3s
retries: 10
web:
image: nginx:${NGINX_TAG:-1.27}
ports:
- "8080:80"
volumes:
- ./site:/usr/share/nginx/html:ro
environment:
- BACKEND_HOST=db
depends_on:
db:
condition: service_healthy
restart: unless-stopped
volumes:
db-data:
# validate the file against the schema (in the sandbox)
yamlschema compose compose.yaml && echo OK
# a typo in a key gives a clear error, for example:
# compose.yaml: services/web: Unevaluated properties are not allowed ('enviroment' was unexpected)
# look at the file's structure: service names and their ports
yq '.services | keys' compose.yaml
yq '.services.web.ports' compose.yaml
# where Docker is available:
# docker compose config # the final file after variable substitution
# docker compose up -d # bring it up in the background
# docker compose logs web # logs of one service
# docker compose down # stop and remove the containers
Pitfalls
- Short-form
depends_ononly waits for the container to start, not for the program inside to be ready. The database may still be initializing while the application is already trying to connect. To wait for readiness you need ahealthcheckon the dependency andcondition: service_healthyon the dependent service. depends_ononly affects startup through compose. If the dependency crashes later, the dependent service won't know: the application itself must be able to reconnect.- Quote ports. Some YAML 1.1 parsers read
22:22as a base-60 number (1342). The string"22:22"is unambiguous. - The order in
portsishost:container."8080:80"opens port 8080 on the host and forwards it to 80 inside the container, not the other way round. Without an address the port listens on all host interfaces. - A named volume must be declared in the top-level
volumes:. A path starting with./or/is a host directory, not a volume. - Inside the network use the service name and the container port (
db:5432), notlocalhostor the host port:localhostin a container is the container itself. environmentbeatsenv_file. If a variable is set in both places,environmentwins.CMDandCMD-SHELLdiffer.["CMD", "pg_isready -U postgres"]looks for a program with spaces in its name. Pass a string with arguments viaCMD-SHELLor split it into list items.- The schema catches typos in keys, not meaning.
yamlschemawon't check whether a volume is declared, whether therestartvalue is valid, whether the image exists or whether the port is free.