Module 05: Docker Compose
Multi-Container Apps

You have covered a lot of ground. Module 02 taught you how to build images with Dockerfiles and layer caching. Module 03 showed you how to persist data outside containers using volumes and bind mounts. Module 04 gave you the networking model: user-defined bridge networks, published ports, and (crucially) container-to-container DNS by service name.

Sam has exactly these three pieces ready: a web API, a Postgres database, and a Redis cache. The goal is to ship them as one app. The problem shows up the moment Sam tries to run it. To start this stack today you would need to:

# 1. create the network manually
docker network create myapp-net

# 2. create the named volume manually
docker volume create pgdata

# 3. start postgres: remember every flag every time
docker run -d --name db --network myapp-net \
  -e POSTGRES_PASSWORD=secret \
  -v pgdata:/var/lib/postgresql/data \
  postgres:16

# 4. start redis
docker run -d --name cache --network myapp-net redis:7-alpine

# 5. build and start the API: hope you remembered the build context
docker build -t myapi:dev .
docker run -d --name api --network myapp-net \
  -p 8000:8000 \
  -e DATABASE_URL=postgresql://postgres:secret@db:5432/app \
  -e REDIS_URL=redis://cache:6379 \
  myapi:dev

Every time Sam tears down and restarts, all of this gets repeated. Every teammate has to know every flag. There's no single source of truth for how the app is configured. This is the problem Compose solves.

Docker Compose is a tool for defining and running multi-container applications from a single declarative YAML file, conventionally named compose.yaml (older projects use docker-compose.yml; the new canonical name is compose.yaml).

You describe your entire application in one file: every service, its image or build context, its ports, its environment variables, its volumes, and how services depend on each other. Then one command brings the whole thing up. This is the file Sam will write once and rerun forever:

# start everything: builds images if needed, creates network/volumes, starts services
docker compose up -d

# tear it all down
docker compose down

Under the hood, Compose does exactly what you would do manually: it creates a user-defined bridge network, creates named volumes, builds or pulls images, and runs containers. The difference is that it reads all the configuration from your YAML file instead of requiring you to type it out every time.

A compose.yaml has three top-level sections: services, volumes, and networks. The most important is services, where each entry under it becomes a container. Here is a fully annotated real-world example, the exact shape of Sam's stack: a web API, a Postgres database, and a Redis cache.

# ── top-level services block ──────────────────────────────────────────
services:

  # ── SERVICE 1: web API (built from a local Dockerfile) ────────────────
  api:
    build: .                          # build from Dockerfile in current dir
    ports:
      - "8000:8000"                  # host:container, publish to the host
    environment:
      DATABASE_URL: postgresql://postgres:${DB_PASS}@db:5432/app
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy  # wait until db passes its healthcheck
      cache:
        condition: service_started  # redis starts fast, just wait for start
    restart: unless-stopped          # restart if it crashes, stop on explicit down
    networks:
      - appnet

  # ── SERVICE 2: Postgres database (pulled from Docker Hub) ─────────────
  db:
    image: postgres:16-alpine        # use an official image, no Dockerfile needed
    environment:
      POSTGRES_PASSWORD: ${DB_PASS}  # variable from .env file or shell
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data # named volume, data survives compose down
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - appnet

  # ── SERVICE 3: Redis cache (pulled from Docker Hub) ────────────────────
  cache:
    image: redis:7-alpine
    restart: unless-stopped
    networks:
      - appnet

# ── named volumes block ────────────────────────────────────────────────
volumes:
  pgdata:                            # Compose creates this volume if it doesn't exist

# ── networks block ─────────────────────────────────────────────────────
networks:
  appnet:                            # Compose creates a user-defined bridge network

The per-service keys explained

Every service in a Compose file needs an image to run from. You tell Compose where to get it in one of two ways, and understanding the distinction is important to get right.

# short form: Dockerfile lives in the same directory as compose.yaml
build: .

# long form: specify a different context and/or Dockerfile name
build:
  context: ./services/api
  dockerfile: Dockerfile.prod

# you can also name the built image (useful for pushing it later)
build: .
image: myorg/myapi:latest

This is where Module 04 pays off. When Compose creates a user-defined bridge network (which it always does, either explicitly or automatically), Docker's embedded DNS resolver is active on that network. Every container gets a DNS entry equal to its service name in the compose file.

That means, inside the api container, you can connect to Postgres using the hostname db, not an IP address, not a port number guessing game. This is identical to what you learned in Module 04 when you put containers on the same user-defined bridge and reached them by name. Compose just automates that setup.

# in your application code (Python example, sketch, not full code)
# the hostname is the Compose SERVICE NAME, not "localhost", not an IP
DATABASE_URL = "postgresql://postgres:secret@db:5432/app"
#                                              ^^
#                                              service name from compose.yaml

REDIS_URL = "redis://cache:6379"
#                    ^^^^^
#                    service name: Compose DNS resolves it to the container's IP

Only expose what needs exposure

Notice in the anatomy example that only the api service has a ports mapping. The db and cache services do not publish ports to the host. They are only reachable from inside the Compose network. This is the correct posture: your database should not be exposed on localhost:5432 in production. Services talk to each other via the Compose network; only the entry point (the API) is published outward.

This section addresses one of the most common real-world bugs with Compose. People add depends_on and then wonder why their app crashes on startup even though it lists the database as a dependency.

The reason is that depends_on alone only controls start order. It tells Compose "start the db container before the api container." It does not wait for the database to actually be ready to accept connections. Postgres takes a few seconds to initialise its data directory after the container starts. Sam's API tried to connect immediately on first boot, and it failed.

Here is the full pattern. You define a healthcheck on the db service, and then reference it in the api's depends_on with condition: service_healthy:

services:

  db:
    image: postgres:16-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      # pg_isready exits 0 when Postgres accepts connections, non-zero otherwise
      interval: 5s    # run the check every 5 seconds
      timeout: 5s     # fail if the check takes more than 5s
      retries: 5      # mark unhealthy after 5 consecutive failures
      start_period: 10s # grace period on first start (don't count failures yet)

  api:
    build: .
    depends_on:
      db:
        condition: service_healthy
        # Compose holds api until db's healthcheck passes

There are three ways to pass environment variables into a Compose service, and knowing when to use each is a real-world skill that signals real maturity.

# 1. inline: simple, but hardcoded values end up committed to git
environment:
  NODE_ENV: production
  PORT: "8000"

# 2. variable substitution: values come from a .env file or from the shell
environment:
  DATABASE_URL: postgresql://postgres:${DB_PASS}@db:5432/app
  # Compose reads .env in the same directory as compose.yaml automatically

# 3. env_file: point to a file; each line is KEY=VALUE
env_file:
  - .env               # loaded automatically anyway, but can list other files
  - .env.local         # useful for per-developer overrides

The .env file

Compose automatically loads a file named .env in the same directory as compose.yaml. Variables defined there are available for ${VAR} substitution anywhere in the compose file. The format is one KEY=VALUE per line, with # for comments:

# never commit this file to git
DB_PASS=supersecretpassword
POSTGRES_DB=app
DEBUG=false

The Compose CLI is built into Docker (as docker compose, note the space, not a hyphen). You will use a small set of commands constantly. Know these cold.

Let's pull everything together and walk through Sam's finished project end to end, from directory layout to running and tearing down. This is the pattern you will use in every containerized project you build.

Directory layout

myapp/
├── compose.yaml         # the whole app in one file
├── .env                 # secrets, gitignored
├── .env.example         # committed placeholder
├── .gitignore           # includes .env
├── Dockerfile           # for the api service
└── src/
    └── main.py          # application code (sketch)

Bring the app up

# from the project root (where compose.yaml lives)
docker compose up -d --build

# what happens:
[+] Building 12.3s (7/7) FINISHED
[+] Running 4/4
 ✔ Network myapp_appnet   Created
 ✔ Volume  myapp_pgdata   Created
 ✔ Container myapp-db-1   Healthy
 ✔ Container myapp-api-1  Started

# confirm everything is running
docker compose ps

# stream logs from all services (Ctrl+C to stop)
docker compose logs -f

# stream logs from one service only
docker compose logs -f api

# open a shell inside the api container to debug
docker compose exec api sh

Tear down

# stop containers + remove network, volumes survive
docker compose down

# stop + remove everything INCLUDING volumes (data is gone)
docker compose down -v

# just stop (don't remove containers)
docker compose stop

This module only sticks if you run it yourself. The checklist below takes about 45 minutes if you go through it properly. Do not skip it.

• Create a project directory and write a compose.yaml with three services: a web app (built from a Dockerfile), a Postgres database, and a Redis cache. Reference the anatomy in Section 2.
• Write a .env file with DB_PASS and add it to .gitignore. Create a .env.example with placeholder values and commit that instead.
• Run docker compose up -d --build. Confirm all three services are running with docker compose ps.
• From inside the api container (docker compose exec api sh), try to connect to the database using the hostname db. Confirm that service-name DNS works.
• Add a healthcheck to the db service and change the api's depends_on to condition: service_healthy. Bring the stack down and up again. Watch Compose wait for the healthcheck to pass before starting the API.
• Scale the api service to 3 replicas with docker compose up -d --scale api=3. Check with docker compose ps. Note: this only works if api has no static host port binding, so change ports to "8000" (container port only) first.
• Run docker compose logs -f and watch log output from all services simultaneously. Then filter to one: docker compose logs -f db.
• Run docker compose down and confirm with docker volume ls that the named volume still exists.
• Run docker compose down -v and confirm the volume is gone. Understand what you just destroyed and why that distinction matters.
• Commit the whole project to a git repository (without .env). Verify a teammate could clone it and run cp .env.example .env && docker compose up -d successfully.