Docker Compose Guide — Multi-Container Development Environments

What Is Docker Compose?

Docker Compose is a tool for defining and running multi-container Docker applications. You describe your entire stack — app, database, cache, message queue — in a single docker-compose.yml file and start everything with one command.

docker compose up -d      # start all services in background
docker compose down       # stop and remove containers
docker compose logs -f    # stream logs from all services
docker compose ps         # show running services

A Production-Ready compose.yml

services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://user:password@db:5432/mydb
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
      interval: 10s
      timeout: 5s
      retries: 5

  cache:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Environment Variables and Secrets

# Use a .env file (not committed to git)
# .env
DATABASE_PASSWORD=supersecret
API_KEY=abc123

# Reference in compose.yml
environment:
  DATABASE_PASSWORD: ${DATABASE_PASSWORD}
  API_KEY: ${API_KEY}

The .env file is automatically loaded by Compose. Never commit it — add it to .gitignore. For production, use Docker secrets or an external secret manager.

Networking Between Services

Compose creates a default network for all services in the same file. Services reach each other by their service name as hostname — app can connect to db:5432 directly.

# Custom networks for isolation
networks:
  frontend:
  backend:

services:
  nginx:
    networks: [frontend, backend]
  app:
    networks: [backend]
  db:
    networks: [backend]

Frequently Asked Questions

What is the difference between docker-compose and docker compose?

docker-compose (v1) is a standalone Python binary. docker compose (v2) is a Go plugin built into the Docker CLI. Use v2 — it's faster and actively maintained.

How do I run one-off commands?

Use docker compose run --rm app python manage.py migrate to run a command in a new container and remove it afterward. Use docker compose exec app bash to open a shell in a running container.