Docker Compose

Overview

Docker Compose lets you define a multi-container application in a single compose.yaml file and start everything with one command. Instead of typing long docker run commands, you declare services, networks, and volumes once. Compose is ideal for local development where an app depends on databases, caches, and other services.

Syntax / Usage

You describe each service under the services key, then bring the whole stack up or down. Compose automatically creates a shared network so services can reach each other by name.

services:
  web:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Examples

Start the whole stack in the background, then view logs and shut it down:

docker compose up -d
docker compose logs -f
docker compose down

Rebuild images after changing a Dockerfile and restart the services:

docker compose up --build

Common Mistakes

• Assuming depends_on waits for the database to be ready (it only waits for start)
• Editing the compose file but forgetting --build after Dockerfile changes
• Hardcoding secrets in the YAML instead of using environment files
• Running docker compose down -v and unexpectedly deleting named volumes
• Using inconsistent indentation, since YAML is whitespace-sensitive

See Also

docker-dockerfile docker-networking docker-volumes