Catalog My learning Blog
Docker and Kubernetes Tutorial: Containers to Production · Phase 2 · Lesson 9 · 4 min read

Docker Compose Tutorial: Multi-Container Apps

On this page
  1. What you'll build with Docker Compose
  2. Step 1: write compose.yaml
  3. Step 2: start the stack with docker compose up
  4. What Docker Compose does for you
  5. depends_on: started is not ready
  6. Step 3: development overrides with compose.override.yaml
  7. Docker Compose vs Kubernetes
  8. Check yourself

What you'll build with Docker Compose

An API, a PostgreSQL database, Redis and a background worker, defined in one compose.yaml and started with docker compose up. A new teammate clones the repository and has the whole stack running in a minute, with no install guide.

Step 1: write compose.yaml

YAML
# compose.yaml
services:
  api:
    build: ./api
    ports:
      - "8080:8080"
    environment:
      ConnectionStrings__Default: "Host=db;Database=shop;Username=shop;Password=${DB_PASSWORD}"
      Redis__Host: "cache:6379"
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

  worker:
    build: ./worker
    environment:
      ConnectionStrings__Default: "Host=db;Database=shop;Username=shop;Password=${DB_PASSWORD}"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17
    environment:
      POSTGRES_DB: shop
      POSTGRES_USER: shop
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shop -d shop"]
      interval: 5s
      timeout: 3s
      retries: 10

  cache:
    image: redis:8-alpine

volumes:
  pgdata:

${DB_PASSWORD} comes from your shell or from a .env file next to compose.yaml, which you don't commit.

If you're following older tutorials: the hyphenated docker-compose (Compose v1) is no longer maintained, and the top-level version: key those files start with is obsolete. Current Docker runs docker compose (v2) and ignores version: with a warning.

Step 2: start the stack with docker compose up

Shell
docker compose up -d --build     # build images, create network and volume, start everything
docker compose ps                # status and health of each service
docker compose logs -f api       # follow one service's logs
docker compose exec db psql -U shop shop
docker compose down              # stop and remove containers and network (volume kept)
docker compose down -v           # ...and delete volumes: the database is wiped
Compose starts every service on a shared project network, so services reach each other by name, with named volumes for data.
Compose starts every service on a shared project network, so services reach each other by name, with named volumes for data.

What Docker Compose does for you

  • A network per project. Every service joins it, and service names resolve through DNS (Day 6). The API connects to db and cache by name. Only api publishes a port.
  • Named volumes declared once and kept across down and up.
  • Startup order: depends_on controls the order containers start in.

depends_on: started is not ready

By default, depends_on waits only until the database container has started, not until PostgreSQL accepts connections. The API starts, tries to connect during PostgreSQL's few seconds of startup, and crashes. Two fixes, best used together:

  1. A healthcheck on the database plus condition: service_healthy, as above: Compose waits until pg_isready succeeds.
  2. Retry with backoff in the application's startup, because in production nothing guarantees order either.

Step 3: development overrides with compose.override.yaml

Compose automatically merges compose.override.yaml if it exists. Use it for development-only settings so the base file stays close to what you'd deploy:

YAML
# compose.override.yaml
services:
  api:
    environment:
      ASPNETCORE_ENVIRONMENT: Development
    volumes:
      - ./api:/src          # bind-mount source for live reload (Day 7)
  db:
    ports:
      - "127.0.0.1:5432:5432"   # reach the database from local tools only

docker compose watch can also sync source changes into containers and rebuild when dependency files change.

Profiles keep optional services out of the default start. Give a service profiles: ["tools"], such as a database admin UI, and it starts only with docker compose --profile tools up.

Docker Compose vs Kubernetes

Compose is ideal for local development, integration tests in CI and small single-host deployments. It doesn't schedule containers across machines or replace failed hosts; that's what Kubernetes is for (Day 15).

Check yourself

Give the database service a healthcheck, such as pg_isready, and set the API's depends_on to condition: service_healthy, so Compose waits until the database actually accepts connections, not just until its container starts. Also add connection retries to the API, because databases can restart later too.

By its service name db on the project network; publishing it isn't needed for the API and would expose it outside the host.

Both stop and remove the stack's containers and its default network. down -v also deletes the named volumes declared in the file, which wipes the database's data. Use plain down to restart cleanly and keep data, and -v only when you truly want a fresh start.

Compose merges it automatically on top of compose.yaml, so you can keep production-like settings in the main file and put development extras, such as bind-mounted source code, debug ports and hot reload, in the override.