Stop 07 · Containers & DockerTopics · 4/9

Docker Compose

In short

Your app needs an API, Postgres and Redis. Starting three containers by hand with the right flags gets old fast. Compose starts the whole set with one command.

A tool for defining and running multi-container applications (e.g. an app plus a database plus a cache) with a single YAML file and a single command — the standard way to run a local development stack.

The blob as a caterer points with a clipboard while three food counters light up at once.

Think of it like this

The wedding caterer's master plan

A caterer doesn't shout instructions to each counter separately. One plan says: chaat here, sweets there, tandoor in the corner, start the tandoor first because it takes longest. Everyone sets up together. docker-compose.yml is that plan for your containers.

Watch it happen

docker compose up

You

Compose

api

docker compose up

1/6Compose reads docker-compose.yml in the current folder.

The big ideas

What you need to know

One file, whole stack

Services, ports, env vars, volumes and networks live in one YAML file you commit with the code.

Service names are hostnames

Inside the network, the api reaches Postgres at db:5432. No IP addresses needed.

Healthchecks beat waiting

depends_on alone only waits for the container to start. Add condition: service_healthy to wait until it's ready.

Daily commands

up -d to start, logs -f api to watch, down to stop. down -v also deletes volumes, so use it carefully.

See it in code

Walk through the code

yaml

1services:2  api:3    build: .4    ports: ["3000:3000"]5    environment:6      DATABASE_URL: postgres://app:secret@db:5432/app7    depends_on:8      db:9        condition: service_healthy10  db:11    image: postgres:1712    environment: { POSTGRES_USER: app, POSTGRES_PASSWORD: secret, POSTGRES_DB: app }13    healthcheck: { test: ["CMD", "pg_isready", "-U", "app"], interval: 5s }14    volumes: [pgdata:/var/lib/postgresql/data]15volumes: { pgdata: {} }

1/4The api service is built from the Dockerfile in this folder and published on port 3000.

Modern Compose doesn't need a version: line at the top. For real secrets, use an env_file that's gitignored instead of writing passwords in the YAML.

Save yourself the pain

Common mistakes

Oops

Using localhost:5432 in the API's DATABASE_URL inside Compose.

Do this instead

Inside a container, localhost is the container itself. Use the service name, db.

Oops

Running docker compose down -v to 'restart cleanly'.

Do this instead

-v deletes your volumes and all your data. Plain down keeps them.

Your mission

API plus Postgres in one command

~30 min

Quick check

Inside Compose, your API can't connect to postgres://localhost:5432. Why?

Go deeper

1Write a docker-compose.yml defining a simple app plus a database service.
2Practice bringing the whole stack up and down with docker-compose up/down.
3Learn how Compose handles networking between services automatically.