Stage 2 · Multi-container apps · Chapter 11 of 20 · 5 min read

Docker Compose

Most real projects are several containers that must find each other. Compose describes the whole stack in one file and starts it with one command.

Why Compose

A real app is several containers plus a network and a volume. Starting them by hand means remembering every flag, in the right order, on every machine.

Reading a compose file

Each key under services becomes a container. The keys inside are the docker run flags you already know, written as YAML.

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"            # the only door from outside
    depends_on: [api]

  api:
    build: ./api             # docker build ./api for you
    environment:
      DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/shop
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}   # read from .env next to this file
      POSTGRES_DB: shop
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "app"]
      interval: 5s
      retries: 10

volumes:
  pgdata:

What it creates

Start order is not readiness

depends_on: [db] only waits for the db container to start, not for Postgres to accept connections, which can take seconds. Give the dependency a healthcheck and wait for condition: service_healthy, as the file above does. Your app should still retry its first connection: databases restart in production too.

The commands you will use

Compose reads a .env file next to compose.yaml to fill in ${DB_PASSWORD}. Keep that file out of Git. A compose.override.yaml, if present, is merged on top automatically, which is a common place for development-only bind mounts.

Try it yourself

1. Step 1 · Write a two-service file

   Work in an empty folder. The folder name becomes the project name.

   $ mkdir demo && cd demo
   $ cat > compose.yaml << 'EOF'
   services:
     web:
       image: nginx:1.27
       ports:
         - "8080:80"
     cache:
       image: redis:7-alpine
   EOF

2. Step 2 · Bring it up

   Compose creates the network first, then both containers on it.

   $ docker compose up -d
    ✔ Network demo_default    Created
    ✔ Container demo-cache-1  Started
    ✔ Container demo-web-1    Started
   $ docker compose ps
   NAME           SERVICE   STATUS         PORTS
   demo-cache-1   cache     Up 3 seconds   6379/tcp
   demo-web-1     web       Up 3 seconds   0.0.0.0:8080->80/tcp

3. Step 3 · Service names resolve

   web finds cache by name with no extra setup, because both are on demo_default.

   $ docker compose exec web getent hosts cache
   172.20.0.2      cache
   $ docker compose exec cache redis-cli ping
   PONG
   $ curl -s -o /dev/null -w '%{http_code}\n' localhost:8080
   200

4. Step 4 · Tear it down

   down removes what up made. There are no volumes here, so nothing is left behind.

   $ docker compose down
    ✔ Container demo-web-1    Removed
    ✔ Container demo-cache-1  Removed
    ✔ Network demo_default    Removed

Recap

• compose.yaml declares services, networks and volumes; docker compose up creates them.
• Every service key maps to a docker run flag you already know.
• Compose makes a project network, so services reach each other by service name.
• depends_on orders start-up; add a healthcheck and service_healthy to wait for readiness.
• down keeps volumes; down -v deletes them.

Quick check