Week 4: Docker Compose & Multi-Container Apps

1. Anatomy of a docker-compose.yml

A Compose file declares a set of services — each roughly corresponding to one docker run command you wrote by hand last week — plus the networks and volumes they share. Docker Compose reads it and creates, starts, connects, and tears down every piece as a single unit.

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:app@db:5432/appdb
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    networks:
      - app-net

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

  cache:
    image: redis:7-alpine
    networks:
      - app-net

networks:
  app-net:

volumes:
  pgdata:

Every top-level key maps directly to something you already know from Week 3: build is the Week 3 Dockerfile, ports is -p host:container, environment is -e, and the top-level networks:/volumes: blocks declare resources that Compose creates for you instead of you running docker network create and docker volume create by hand.

2. Running a Multi-Service App

With the file above saved as docker-compose.yml, the entire stack — app, database, and cache — comes up with one command:

docker compose up              # build/pull images and start every service, attached
docker compose up -d           # same, but detached (runs in the background)
docker compose up --build      # force a rebuild of any service with a "build:" key
docker compose ps              # list services and their status
docker compose logs -f web     # stream logs for a single service
docker compose logs -f         # stream logs for every service, interleaved

Compose prefixes every log line with the service name, so a multi-service app's combined log stream is still readable — you can see the app container's request log and the database's query log side by side without losing track of which container produced which line.

docker compose down             # stop and remove containers, and the default network
docker compose down -v          # also remove named volumes -- deletes persisted data!
docker compose restart web      # restart a single service without touching the others
docker compose exec web sh      # shell into a running service, same idea as docker exec

Notice docker compose down alone leaves your named volumes intact — a deliberate safety default, since tearing down a stack for a code change shouldn't silently delete a development database. Only the explicit -v flag destroys volume data.

3. Service Dependencies & Compose Networks

depends_on controls start order, not readiness — by default, Compose only waits for a dependency's container to start, not for the service inside it to actually be ready to accept connections. A plain Postgres container reports "started" the instant its process launches, well before it's actually accepting queries, which is exactly the kind of race condition that makes an app crash on its first connection attempt right after docker compose up.

The healthcheck block on the db service and the condition: service_healthy under web's depends_on fix this properly: Compose runs pg_isready every 5 seconds and won't consider db healthy — and won't start web — until Postgres is actually ready to accept connections.

$ docker compose ps
NAME              IMAGE                COMMAND                  STATUS
myapp-db-1        postgres:16-alpine   "docker-entrypoint.s…"   Up 12 seconds (healthy)
myapp-cache-1     redis:7-alpine       "docker-entrypoint.s…"   Up 12 seconds
myapp-web-1       myapp-web            "node dist/server.js"    Up 8 seconds

Compose creates a single default network for the whole stack (or, as shown above, you can name one explicitly with a top-level networks: block) and gives every service DNS resolution by its service name — the same name-based discovery you set up manually with docker network create in Week 3, except Compose wires it up automatically for every service listed in the file. Inside the web container, the hostname db and cache simply resolve, no IP addresses or manual network commands required.

4. Named Volumes & Persistence

The top-level volumes: block declares named volumes exactly like docker volume create did in Week 3, and a service references one under its own volumes: key with the same name:path syntax you used with docker run -v. Compose creates the volume automatically the first time the stack comes up if it doesn't already exist.

services:
  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data   # named volume: survives "compose down"
  web:
    build: .
    volumes:
      - ./src:/app/src                    # bind mount: live-reload during local dev

volumes:
  pgdata:
    # empty block = Compose manages this volume with default settings

This mirrors the distinction from Week 3 exactly: the database gets a named volume because its data must outlive any single container recreation, while the app service can use a bind mount to your local ./src directory purely for development convenience — editing a file on your host shows up inside the running container immediately, without a rebuild.

docker volume ls                       # see volumes Compose created, prefixed with the project name
docker volume inspect myapp_pgdata     # where it actually lives on disk, and its driver
docker compose down                    # containers gone, pgdata volume untouched
docker compose up -d                   # new db container, same pgdata volume -- same data

5. Hands-on Exercise

6. Knowledge Check

Four quick questions. Expand each to check your answer.