Introduction to Docker Compose
Most applications consist of multiple services - an API, a database, a cache, a message broker, and
perhaps a scheduler. Managing these individually with docker run commands leads to
mistakes: forgotten network flags, mismatched passwords, and uncertainty about which container runs
on which port. Docker Compose solves this by describing the entire stack in a single YAML file and
bringing it up with one command, eliminating the guesswork of multi-container deployments.
What Docker Compose Is
Docker Compose is the tool that ships with Docker for defining and running multi-container applications.
You declare services, networks, and volumes in a compose.yaml file (the old name
docker-compose.yml still works), and docker compose up -d creates the network,
pulls the images, builds what needs building, and starts everything in dependency order.
One naming note that confuses people: the modern command is docker compose (a Docker
plugin, with a space) — the standalone docker-compose binary is the older v1 tool. Both read
the same file; modern files no longer need a version: key at the top, and if you see one in
an old guide you can safely drop it.
A Compose File That Looks Like Real Life
This is the shape of a typical stack: an API built from a local Dockerfile, a PostgreSQL database, and health checks so the API does not start before the database is actually ready:
services:
api:
build: ./api
ports:
- "3000:3000"
environment:
- DB_HOST=db
- DB_USER=postgres
- DB_PASSWORD=${DB_PASSWORD}
depends_on:
db:
condition: service_healthy
restart: unless-stopped
db:
image: postgres:16
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=${DB_PASSWORD}
- POSTGRES_DB=myapp
volumes:
- pgdata:/var/lib/postgresql/data
ports:
- "5432:5432"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 3s
retries: 5
volumes:
pgdata:
Compared with a "hello world" example, the practical differences that actually matter in daily use:
- No
version:key — the current Compose spec does not need it. depends_onwithcondition: service_healthy— plaindepends_ononly waits for the container to start, not for the database to accept connections. Without the healthcheck, the API starts, fails to connect, and exits — and you get to explain why the stack "randomly" worked on the second run.${DB_PASSWORD}from a.envfile — Compose reads a.envfile in the same directory and substitutes variables. Passwords in compose files get committed to git eventually; environment variables do not.restart: unless-stopped— the API comes back after a reboot or crash without you noticing the outage. The default policy isno, which is usually the wrong choice for a service you expect to stay up.
How Compose Networking Works
Compose creates a default network for the project, and every service can reach every other service by
service name: inside the API container, the database is reachable at db:5432
rather than localhost:5432 (inside the container, localhost is the container itself). This is
why the API uses DB_HOST=db. You never need to know the database container's IP address —
Compose's built-in DNS handles it, and that is also the basis of the
bridge network model.
The Commands You Will Actually Use
docker compose up -d— build and start everything in the background. Without-dit runs in the foreground and Ctrl+C stops the stack.docker compose up -d --build— rebuild images before starting; see docker compose up --build for when this matters.docker compose logs -f— tail logs from all services; add a service name to limit to one.docker compose exec api sh— open a shell inside a running service.docker compose down— stop and remove containers and the default network. Volumes are kept, so the database survives;docker compose down -vremoves volumes too — use it only when you mean to destroy data.docker compose ps— status of the services in the current directory's project.
Problems You Will Hit and Why
The most common failure with this file is a port conflict: if anything else on the host
already listens on 5432 (a natively installed PostgreSQL, for instance), up
fails with bind: address already in use. The container's internal port stays the same —
change only the left-hand side of the mapping, e.g. "5433:5432", and update
DB_PORT in the API.
The second classic: docker compose down followed by "where did my data go?" — data is safe
because it lives in the named pgdata volume, not in the container. Containers are ephemeral;
volumes are the point of persistence, which matters when you
back up and restore databases.
Where to Go Next
- docker compose up --build — rebuild semantics
- Creating Docker Networks for Container Communication
- Disabling auto-start for a container
- Why Docker builds fail differently on Linux and Windows
Compose removes the "which container, which port, which network" guesswork from a multi-service stack. The file above is a solid template: a healthchecked database, an API that waits for it, secrets outside the repo, and a restart policy that keeps things running.