/docker-compose

name: docker-compose
description: Multi-container Docker applications with docker-compose — define services, networks, volumes, and orchestrate local development environments
tags: [docker, containers, devops, orchestration, development]
origin: unknown
source_license: see upstream
language: en

Docker Compose — Multi-Container Orchestration

Manage multi-container Docker applications with docker-compose. Define services, networks, volumes, and dependencies in YAML. Perfect for local development, testing, and simple production deployments.

When to Use

• Setting up local development environments
• Running multi-service applications (app + database + cache)
• Testing microservices locally
• CI/CD pipeline containers
• Simple production deployments

Core Concepts

Services

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

volumes:
  db-data:

Networks

networks:
  frontend:
  backend:

services:
  app:
    networks:
      - frontend
      - backend
  
  db:
    networks:
      - backend

Common Patterns

1. Full-Stack App (Frontend + Backend + Database)

version: '3.8'

services:
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    environment:
      - REACT_APP_API_URL=http://localhost:8000
    depends_on:
      - backend

  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/myapp
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=myapp
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

2. Microservices with Redis Cache

services:
  api:
    build: ./api
    ports:
      - "8000:8000"
    environment:
      - REDIS_URL=redis://cache:6379
    depends_on:
      - cache
      - db

  worker:
    build: ./worker
    environment:
      - REDIS_URL=redis://cache:6379
    depends_on:
      - cache

  cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  db:
    image: postgres:15
    environment:
      - POSTGRES_PASSWORD=secret
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

3. Development with Hot Reload

services:
  app:
    build:
      context: .
      target: development
    volumes:
      - .:/app
      - /app/node_modules
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    command: npm run dev

Essential Commands

# Start all services
docker-compose up

# Start in background
docker-compose up -d

# Build and start
docker-compose up --build

# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f app

# Execute command in service
docker-compose exec app sh

# Scale service
docker-compose up -d --scale worker=3

# Restart service
docker-compose restart app

# View running services
docker-compose ps

Best Practices

1. Use .env Files

# .env
POSTGRES_PASSWORD=secret
API_PORT=8000

# docker-compose.yml
services:
  db:
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
  
  api:
    ports:
      - "${API_PORT}:8000"

2. Health Checks

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

3. Resource Limits

services:
  app:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M

4. Named Volumes for Persistence

volumes:
  postgres-data:
    driver: local
  redis-data:
    driver: local

5. Separate Dev/Prod Configs

# Development
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

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

Troubleshooting

Port Already in Use

# Find process using port
lsof -i :3000

# Change port in docker-compose.yml
ports:
  - "3001:3000"

Container Won't Start

# Check logs
docker-compose logs app

# Check service status
docker-compose ps

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

Database Connection Issues

# Ensure depends_on is set
depends_on:
  - db

# Use service name as hostname
DATABASE_URL=postgresql://user:pass@db:5432/myapp

# Wait for database to be ready (use wait-for-it.sh or healthcheck)

Volume Permission Issues

# Set user in Dockerfile
USER node

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

Production Considerations

1. Use Specific Image Tags

# ❌ Don't use latest
image: postgres:latest

# ✅ Use specific version
image: postgres:15.3-alpine

2. Secrets Management

# Use Docker secrets (Swarm mode)
secrets:
  db_password:
    file: ./secrets/db_password.txt

services:
  db:
    secrets:
      - db_password

3. Logging

services:
  app:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

4. Restart Policies

services:
  app:
    restart: unless-stopped

Integration with CI/CD

# .github/workflows/test.yml
- name: Run tests
  run: |
    docker-compose -f docker-compose.test.yml up --abort-on-container-exit
    docker-compose -f docker-compose.test.yml down -v

Common Stacks

MERN Stack

services:
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
  
  backend:
    build: ./backend
    ports:
      - "5000:5000"
  
  mongo:
    image: mongo:6