Run multi-container apps with Compose — Containers Chapter 8

$ run as a normal user# run as root (or with sudo)

Write a compose file

Each service is a container; Compose creates a network where services find each other by name.

compose.yaml

services:
  web:
    image: nginx:1.27
    ports: ["8080:80"]
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      api:
        condition: service_healthy
  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://shop:${DB_PASSWORD}@db:5432/shop
    healthcheck:
      test: ["CMD", "curl", "-fs", "http://localhost:8080/health"]
      interval: 10s
      retries: 5
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: shop
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: shop
    volumes: [pgdata:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shop"]
      interval: 5s
      retries: 10
volumes:
  pgdata:

.env

DB_PASSWORD=change-me-locally

8.2

Run the app

docker compose (or podman compose) works on the whole project.

$docker compose up -d
$docker compose ps
$docker compose logs -f api
$docker compose exec db psql -U shop
$docker compose up -d --build api
$docker compose pull && docker compose up -d
$docker compose down
$docker compose down -v
$docker compose config

Command	Does
`up -d`	Create and start everything in the background
`up -d --build`	Rebuild images first
`down` / `down -v`	Stop and remove (and with `-v` delete volumes!)
`config`	Show the final file with variables filled in

8.3

Wait for real readiness

depends_on alone only waits for the container to start. With condition: service_healthy, Compose waits for the health check to pass.

8.4

Use files per environment

A base file plus an override file per environment.

$docker compose -f compose.yaml -f compose.prod.yaml up -d
$docker compose --profile debug up -d

compose.override.yaml is read automatically in development.
Profiles start extra services only when asked (for example a debug tool).

Watch out

The .env file is for local values. Never commit real production secrets in it; use a secret store or Compose secrets:.

8.5

Know when to move on

Compose runs on one host. When you need many hosts, self-healing, rolling updates and autoscaling, move to Kubernetes — see CKA. Tools like Kompose can turn a compose file into Kubernetes manifests as a start.

All commands in this chapter

docker