Docker Compose Cheat Sheet — Complete Reference Guide (2025)

Introduction: What is Docker Compose?

Docker Compose is a powerful tool that allows you to define and run multi-container Docker applications with a single command. Instead of manually running multiple docker run commands for each service, you write a declarative docker-compose.yml configuration file that describes your entire application stack.

Why Use Docker Compose?

• Simplified Multi-Container Orchestration: Manage complex applications with multiple services (web servers, databases, caches) effortlessly
• Environment Consistency: Ensure development, staging, and production environments use identical configurations
• Faster Development: Spin up entire development environments with a single command
• Service Networking: Automatic DNS resolution between containers—no port mapping headaches
• Volume Management: Persist data across container restarts with named volumes
• Environment Variables: Manage configuration centrally with .env files
• Infrastructure as Code: Version control your entire application stack

Docker Compose is perfect for development, testing, and small production deployments. For large-scale deployments, Kubernetes is recommended.

Installation & Quick Reference

Install Docker Compose (v2+)

Docker Compose v2+ comes bundled with Docker Desktop and Docker Engine on Linux.

Verify Installation

# Check version
docker compose version

# Should output: Docker Compose version 2.x.x

Install on Linux (if not included)

curl -L https://github.com/docker/compose/releases/download/v2.24.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
docker compose version

docker-compose.yml Structure & YAML Reference

The docker-compose.yml file is the blueprint for your entire application. Here's the complete structure with all available options:

Basic File Structure

version: '3.9'

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    networks:
      - frontend

  api:
    build:
      context: ./app
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - DB_HOST=postgres
    depends_on:
      - postgres
    networks:
      - backend

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_PASSWORD=secret123
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - backend

volumes:
  db_data:

networks:
  frontend:
  backend:

Complete Service Configuration Reference

Version Compatibility

Use version 3.9 or higher for most modern use cases:

Healthcheck Configuration

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

Essential Docker Compose Commands

Command Variations & Useful Flags

# Run with specific compose file
docker compose -f docker-compose.prod.yml up -d

# Run in project directory
cd /path/to/project && docker compose up

# Scale specific service
docker compose up --scale api=3

# View logs with timestamps
docker compose logs --timestamps

# Follow logs from specific service
docker compose logs -f postgres

# Rebuild without cache
docker compose build --no-cache api

# Run interactive shell
docker compose exec -it api bash

# Display environment variables in container
docker compose exec api printenv

Common Patterns & Real-World Examples

Pattern 1: Multi-Container Web Application (Nginx + Node.js + PostgreSQL)

version: '3.9'

services:
  nginx:
    image: nginx:latest
    container_name: app_nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
      - ./html:/usr/share/nginx/html:ro
    depends_on:
      - api
    networks:
      - frontend
    restart: unless-stopped

  api:
    build:
      context: ./app
      dockerfile: Dockerfile
    container_name: app_api
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_USER=appuser
      - DB_PASSWORD=secure_password
    volumes:
      - ./app:/app
      - /app/node_modules
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - frontend
      - backend
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  postgres:
    image: postgres:15-alpine
    container_name: app_postgres
    environment:
      - POSTGRES_USER=appuser
      - POSTGRES_PASSWORD=secure_password
      - POSTGRES_DB=appdb
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    networks:
      - backend
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

networks:
  frontend:
  backend:

Pattern 2: Development vs Production Configuration

docker-compose.yml (base):

version: '3.9'
services:
  api:
    build: ./app
    ports:
      - "3000:3000"
    environment:
      - DB_HOST=postgres
    volumes:
      - ./app:/app

docker-compose.override.yml (development):

services:
  api:
    environment:
      - NODE_ENV=development
      - DEBUG=*
    command: npm run dev

docker-compose.prod.yml (production):

services:
  api:
    environment:
      - NODE_ENV=production
      - DEBUG=false
    command: npm run start
    restart: always
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M

Usage:

# Development
docker compose up

# Production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Pattern 3: Environment Variable Management with .env

.env file:

# Database
DB_HOST=postgres
DB_USER=appuser
DB_PASSWORD=my_secure_password_here
DB_NAME=production_db

# Application
NODE_ENV=production
APP_PORT=3000
LOG_LEVEL=info

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

docker-compose.yml:

version: '3.9'
services:
  api:
    image: myapp:latest
    environment:
      - DB_HOST=${DB_HOST}
      - DB_USER=${DB_USER}
      - DB_PASSWORD=${DB_PASSWORD}
      - DB_NAME=${DB_NAME}
      - NODE_ENV=${NODE_ENV}
      - APP_PORT=${APP_PORT}

Variables in ${VAR} format are automatically replaced from .env file.

Pattern 4: Networking Between Services

version: '3.9'

services:
  frontend:
    image: frontend:latest
    networks:
      - frontend_net

  api:
    image: api:latest
    networks:
      - frontend_net
      - backend_net
    # Frontend can reach API at http://api:3000

  database:
    image: postgres:15
    networks:
      - backend_net
    # API can reach database at postgres://database:5432

networks:
  frontend_net:
    driver: bridge
  backend_net:
    driver: bridge

Troubleshooting — 5 Common Issues & Solutions

Issue 1: "ERROR: Service 'api' failed to build"

Solution:

# View detailed build output
docker compose build --no-cache api

# Check Dockerfile syntax
docker build --dry-run ./app

Issue 2: "Cannot connect to service: Connection refused"

Solution:

# Verify all services are running
docker compose ps

# Check service logs for startup errors
docker compose logs postgres

# Ensure services are on same network
docker compose exec api ping postgres

# Use depends_on with service_healthy condition
# In docker-compose.yml:
# depends_on:
#   postgres:
#     condition: service_healthy

Issue 3: "Volume mount permission denied"

Solution:

# Fix permissions on host
chmod 755 /path/to/volume

# Or specify user in docker-compose.yml
user: "1000:1000"

# For database volumes, use proper ownership
chown -R 999:999 ./postgres_data

Issue 4: "Docker Compose hangs or times out"

Solution:

# Increase timeout for depends_on
# docker-compose.yml: start_period in healthcheck

# View service logs in real-time
docker compose logs -f

# Force stop (use cautiously)
docker compose kill

# Clear everything and restart
docker compose down -v
docker compose up --build

Issue 5: "Out of disk space" or "Cannot write to volume"

Solution:

# Check disk usage
docker system df

# Remove unused volumes
docker volume prune

# List all volumes
docker volume ls

# Remove specific volume (use with caution!)
docker volume rm volume_name

# Clean everything (development only)
docker compose down -v
docker system prune -a --volumes

Frequently Asked Questions

docker compose restart postgres

docker compose stop postgres
docker compose start postgres

volumes:
  - /host/path:/container/path         # Bind mount
  - named_volume:/container/path        # Named volume
  - ./relative/path:/container/path     # Relative path

Key Takeaways

• ✅ Docker Compose simplifies multi-container orchestration with a single docker-compose.yml file
• ✅ Use version 3.9+ for all features including healthchecks and dependencies
• ✅ Services communicate via service name as hostname on custom networks
• ✅ Manage configuration with .env files for environment variables
• ✅ Use healthcheck and depends_on: {condition: service_healthy} for reliable startup order
• ✅ Named volumes persist data even after docker compose down
• ✅ For production: single server ✓, large scale → Kubernetes or Docker Swarm