How to write a Docker Compose file
Docker Compose describes several containers in one YAML file and starts them together with one command. This page walks through a small web app with a database, key by key, and lists the mistakes that cause most first-run errors.
What Compose is for
Running one container is a single docker run command. Running an app, its database and a cache means three long commands, a shared network and the right start order. Compose writes that down. You keep a file called compose.yaml (older projects use docker-compose.yml, which still works) and run docker compose up.
A working example
services:
web:
build: .
ports:
- "8080:3000"
environment:
DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
depends_on:
db:
condition: service_healthy
db:
image: postgres:16
environment:
POSTGRES_USER: app
POSTGRES_DB: app
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- dbdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app"]
interval: 5s
retries: 10
volumes:
dbdata:
Key by key
| Key | What it means here |
|---|---|
services | Each child is one container definition: web and db |
build: . | Build an image from the Dockerfile in this folder |
image | Use a published image and tag instead of building |
ports | "HOST:CONTAINER": your browser uses 8080, the app listens on 3000 |
environment | Variables passed into the container |
volumes | Persistent storage; dbdata survives container rebuilds |
healthcheck | A command Docker runs to decide whether the service is ready |
depends_on | Start order; with service_healthy, wait for the healthcheck |
Notice the database host in DATABASE_URL is just db. Compose puts all services on one private network where each service name works as a host name. Inside that network the database is reached on its own port 5432; it is not published to your machine at all, which is a good default.
Keeping secrets out of the file
${DB_PASSWORD} is filled in from your shell or from a file named .env next to compose.yaml. Put the real value in .env, add that file to .gitignore, and commit a .env.example with placeholder values so others know what to set.
Day-to-day commands
docker compose up -d # start everything in the background
docker compose ps # what is running, and on which ports
docker compose logs -f web # follow one service's output
docker compose exec db psql -U app # open a shell tool inside a container
docker compose down # stop and remove containers (volumes stay)
docker compose down -v # also delete named volumes: data is gone
docker compose config # print the file after variables are filled in
Common mistakes
- Using
localhostbetween containers. Inside a container, localhost means that same container. Use the service name. - Swapping the port numbers. The left number is on your machine, the right one inside the container.
"3000:8080"and"8080:3000"are different setups. - Expecting
depends_onalone to wait for readiness. Without a healthcheck condition it only waits for the container to start, not for the database to accept connections. - Running
down -vcasually. It deletes the database volume. Back up first. - Tabs in YAML. Indent with spaces only.
Questions
Do I still need the version: line at the top?
No. Current Docker Compose ignores the top-level version key and prints a warning that it is obsolete. You can delete it.
Is Compose meant for production?
It suits single-host deployments and development well. Multi-machine setups usually move to an orchestrator, but the service definitions translate fairly directly.
How do I rebuild after changing the Dockerfile?
Run docker compose up -d --build. Without --build, Compose reuses the image it built before.