🐳 Lesson 5: Docker Compose

The Problem Compose Solves

A real application is rarely a single container. A typical web app is a web frontend, an API, and a database — three containers that must be built, configured, networked together, and started in the right order. Run that by hand and you're typing something like this, over and over:

docker network create app-net
docker volume create db-data
docker run -d --name db --network app-net -v db-data:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=secret postgres:16-alpine
docker run -d --name api --network app-net -e DATABASE_URL=postgres://db:5432/app \
  -p 8000:8000 myapp-api
docker run -d --name web --network app-net -p 8080:80 myapp-web

That's fragile, hard to share, and impossible to remember. Docker Compose replaces all of it with a single declarative file. You describe the desired state — which services exist, how they're built, what they connect to — and Compose makes it real with one command:

docker compose up -d

💡 It's docker compose, with a space. Compose is now a plugin built into the Docker CLI (Compose v2). The old standalone docker-compose binary (v1, hyphenated) reached end-of-life and should no longer be used. Every command in this lesson uses the modern docker compose form.

Anatomy of compose.yaml

The canonical filename today is compose.yaml. The older names docker-compose.yml and docker-compose.yaml still work and are auto-detected, but compose.yaml is what the Compose Specification recommends for new projects.

Here is a minimal, valid file — note it opens straight into services::

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

Each service supports a rich set of keys. The ones you'll reach for constantly:

image vs build

Use image when someone else already published what you need (databases, caches, proxies). Use build when the service is your code:

services:
  db:
    image: postgres:16-alpine          # pull a ready-made image
  api:
    build:                             # build your own from a Dockerfile
      context: ./api
      dockerfile: Dockerfile

depends_on and healthchecks

A plain depends_on only waits for a container to start, not for the program inside to be ready. A database process takes a moment to accept connections, so your API can still crash on boot. The robust fix is a healthcheck plus the condition: service_healthy form:

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

  api:
    build: ./api
    depends_on:
      db:
        condition: service_healthy     # wait until db reports healthy

⚠️ Note: Even with healthchecks, well-written apps should still retry their first database connection. Startup ordering reduces flakiness; it isn't a substitute for resilient code.

A Complete Worked Stack

Let's assemble a realistic three-tier app: an Nginx web frontend, a Node API we build ourselves, and a Postgres database whose data lives in a named volume — all on a private network.

# compose.yaml — a web + api + database stack
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    depends_on:
      - api
    networks:
      - frontend

  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://appuser:secret@db:5432/appdb
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
    networks:
      - frontend
      - backend
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - backend

volumes:
  db-data:

networks:
  frontend:
  backend:

Notice the shape: three services, a volumes: block declaring the named db-data volume, and a networks: block declaring two private networks. The db sits only on backend, so the web tier can't reach it directly — only the api bridges both.

Bring it up

docker compose up -d

[+] Running 5/5
 ✔ Network app_frontend   Created
 ✔ Network app_backend    Created
 ✔ Volume "app_db-data"   Created
 ✔ Container app-db-1     Healthy
 ✔ Container app-api-1    Started
 ✔ Container app-web-1    Started

Check what's running, then watch the logs stream by:

docker compose ps
docker compose logs -f

NAME         IMAGE              SERVICE   STATUS                   PORTS
app-api-1    app-api            api       Up 20 seconds            0.0.0.0:8000->8000/tcp
app-db-1     postgres:16-alpine db        Up 25 seconds (healthy)
app-web-1    nginx:alpine       web       Up 19 seconds            0.0.0.0:8080->80/tcp

Scale a service

Need more API workers? Scale horizontally without editing the file:

docker compose up -d --scale api=3

Compose starts three api containers sharing the same network; a reverse proxy or load balancer in front distributes requests across them. (Only stateless services should be scaled this way — never scale a single-writer database.)

Tear it down

docker compose down

This stops and removes the containers and networks — but keeps your named volume, so the database survives. To wipe the data too, add -v:

docker compose down -v      # also removes the db-data volume

⚠️ Careful: docker compose down -v deletes named volumes declared in the file. That erases your database. Use it deliberately.

Service-to-Service Networking

This is the piece that surprises newcomers most. When Compose creates a network, it also runs an embedded DNS server. Every service is reachable from every other service on that network by its service name as the hostname. No IP addresses, no links, no manual config.

So in our stack, the API connects to Postgres at the host db — because the service is named db:

    environment:
      DATABASE_URL: postgres://appuser:secret@db:5432/appdb
      #                                        ^^ the service name

Volumes & Persistence

Containers are ephemeral — remove one and everything written inside it is gone. That's fine for stateless apps, catastrophic for a database. Volumes are how Compose keeps data alive across restarts and rebuilds.

Named volumes — for data that must survive

A named volume is managed by Docker and outlives any single container. Declare it under the top-level volumes: key and mount it into the service:

services:
  db:
    image: postgres:16-alpine
    volumes:
      - db-data:/var/lib/postgresql/data   # named volume → survives down/up

volumes:
  db-data:

Bind mounts — for development

A bind mount maps a folder on your host straight into the container. Edit a file on your laptop and the container sees it instantly — perfect for iterating on source code:

services:
  api:
    build: ./api
    volumes:
      - ./api/src:/app/src   # host path : container path

💡 Tip: Inspect what Docker is managing with docker volume ls. Compose prefixes volume names with the project name, so db-data shows up as app_db-data.

The Modern Dev Workflow

🚀 docker compose watch — live sync and rebuild

The standout modern feature. Instead of bind-mounting and hoping your framework hot-reloads, docker compose watch lets you declare exactly what should happen when files change: sync files into the running container, or rebuild the image when dependencies change. Add a develop.watch block to the service:

services:
  api:
    build: ./api
    develop:
      watch:
        - action: sync              # copy changed source into the container
          path: ./api/src
          target: /app/src
        - action: rebuild           # rebuild when dependencies change
          path: ./api/package.json

Then start watching:

docker compose watch

[+] Running 3/3
 ✔ Container app-db-1   Healthy
 ✔ Container app-api-1  Started
 ✔ Container app-web-1  Started
⦿ watching service "api" for changes...
Syncing "api" after changes: api/src/routes.js

Edit api/src/routes.js and Compose syncs it in place; change package.json and it rebuilds the image automatically. It's the cleanest inner-loop Compose has ever had.

Override files

Compose automatically merges a compose.override.yaml on top of your base compose.yaml. Keep production-safe defaults in the base file, and put developer conveniences (bind mounts, debug env vars, exposed ports) in the override:

# compose.override.yaml — merged automatically in dev
services:
  api:
    environment:
      NODE_ENV: development
    volumes:
      - ./api/src:/app/src

To run without the override (e.g. a production-like run), name your files explicitly:

docker compose -f compose.yaml -f compose.prod.yaml up -d

Profiles

Profiles let one file describe optional services that only start when asked for. Tag a service with profiles: and it stays dormant until you enable its profile:

services:
  api:
    build: ./api
  debug-tools:
    image: nicolaka/netshoot
    profiles: [debug]      # only starts when the "debug" profile is active

docker compose --profile debug up -d

docker scout quickview
docker scout cves app-api

Try It Yourself

Time to build a real stack from scratch — a small web page served by Nginx plus a Postgres database — bring it up, prove it works, and tear it down.

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

docker compose up -d
docker compose ps
docker compose logs -f db     # Ctrl-C to stop following
docker compose down           # containers gone, db-data volume kept
docker compose up -d          # data is still there

Quick Quiz

Summary

📚 Additional Resources

• Docker Compose overview — the official docs
• Compose file reference — every key, current spec
• Use Compose Watch — the live-reload workflow in depth
• Using profiles with Compose — optional services on demand

🚀 What's Next?

You can now orchestrate a full multi-container stack locally. Next, we'll push into production territory — registries, deeper networking, image optimization, and the deployment strategies that take these ideas beyond your laptop.