Introduction to Docker Compose

Docker Compose is a tool for defining and running multi-container applications using a single compose.yaml YAML file. Instead of running multiple docker run commands with long flag lists, you declare all services, networks, and volumes declaratively and start everything with docker compose up. The format is version-controlled alongside the application code. The services key defines each container: its image or build context, environment variables, port mappings, volume mounts, network membership, and dependency order. The networks key creates named networks. The volumes key creates named volumes. Services on the same network can reach each other by service name without any additional configuration. Compose is now a Docker CLI plugin (docker compose) replacing the older standalone docker-compose Python tool. The v2 plugin is faster, supports profiles, and uses BuildKit by default. The compose.yaml filename is preferred over docker-compose.yml for new projects, though both are recognised.

Example

# compose.yaml
services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "appuser"]
      interval: 10s
      timeout: 5s
      retries: 5

  api:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      DATABASE_URL: postgres://appuser:secret@db:5432/appdb
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - uploads:/app/uploads

volumes:
  pgdata:
  uploads:

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

HTML

Full Editor

Related Resources

Docker Reference

Complete tag & property list

Docker How-To Guides

Step-by-step practical guides

Docker Exercises

Practice what you've learned