Docker Compose: multi-container apps

Why Compose?

Running a web app, Postgres and Redis by hand means three long docker run commands, a network, two volumes and the right order, typed the same way on every laptop. Docker Compose puts all of this in one YAML file in the repository. Anyone can clone the project and run one command to get the whole stack.

Compose v2 is a plugin of the Docker CLI, so the command is docker compose, with a space. The old standalone docker-compose (with a hyphen) is the retired v1. The preferred file name is compose.yaml (docker-compose.yml still works), and the old top-level version: key is obsolete: Compose ignores it, so leave it out.

A real example: a small e-commerce store

A small Jaipur startup sells block-printed fabrics online. Its stack is a Node.js storefront, PostgreSQL for orders and Redis for sessions and the cart.

services:
  web:
    build: .                       # build from the Dockerfile in this folder
    ports:
      - "8080:3000"
    env_file: .env                 # app settings, never committed
    environment:
      DATABASE_URL: postgres://shop:${POSTGRES_PASSWORD}@db:5432/shop
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy   # wait until Postgres answers
      cache:
        condition: service_started
    restart: unless-stopped

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

  cache:
    image: redis:7.4-alpine
    volumes:
      - redisdata:/data
    restart: unless-stopped

volumes:
  pgdata:
  redisdata:

Reading the file

• services: each entry becomes one or more containers. The key (web, db, cache) is also the host name other services use.
• image or build: use a ready image, or build one from a Dockerfile.
• ports: publish to the host, host first. Only web is published; db and cache are reachable only inside the Compose network, which is safer.
• environment and env_file: set variables. Compose also reads a file called .env in the project folder to fill in ${VARIABLES} in compose.yaml.
• volumes: the top-level section declares named volumes; the service section mounts them.
• networks: Compose creates a default network for the project automatically. Add your own only when you need to separate groups of services.
• depends_on: start order. The plain list form only waits for the container to START. With condition: service_healthy, Compose waits until that service's healthcheck passes.
• healthcheck: the command Docker runs to decide whether the service is healthy.
• restart: the same restart policies as docker run.

The commands

docker compose up -d          # create network, volumes and containers; start in the background
docker compose up -d --build  # rebuild images first (after code or Dockerfile changes)
docker compose ps             # status and health of each service
docker compose logs -f web    # follow one service's logs
docker compose exec db psql -U shop shop   # run a command in a running service
docker compose build          # just build the images
docker compose down           # stop and remove containers and the network (volumes stay)
docker compose down -v        # ALSO delete the named volumes: your database is gone

Profiles and override files

Profiles let you include optional services only when asked. Services without a profile always start; a service with profiles starts only when you enable that profile.

  adminer:                      # a small web UI for the database
    image: adminer
    ports:
      - "8081:8080"
    profiles: ["debug"]

Override files change settings per environment. If a compose.override.yaml file exists, Compose merges it on top of compose.yaml automatically, which is handy for development extras such as bind-mounting the code. For other setups, list files explicitly: docker compose -f compose.yaml -f compose.prod.yaml up -d. Later files override earlier ones.

Common mistakes

• Using depends_on without a healthcheck and expecting the database to be ready: the container may have started, but Postgres needs a few seconds before it accepts connections. Use condition: service_healthy, and still make the app retry its connection.
• Connecting to localhost from the web container. Inside a container, localhost is the container itself; use the service name (db, cache).
• Committing .env with real passwords. Commit a .env.example with dummy values and add .env to .gitignore.
• Treating Compose as a production cluster. Compose is great for development, CI and small single-server deployments; for many servers and automatic failover, teams move to Kubernetes or a managed container service.