Docker Compose for Modern Development: Complete 2026 Guide

Docker Compose has evolved into an essential tool for modern software development. This comprehensive guide covers everything you need to know about Docker Compose in 2026, from basic concepts to advanced production patterns.

Why Docker Compose in 2026?

Docker Compose simplifies multi-container application management by allowing you to define your entire application stack in a single YAML file. Key benefits include:

Reproducible environments across development, staging, and production
Easy service orchestration with dependency management
Built-in networking between containers
Volume management for persistent data
Environment variable support for configuration

Installation

macOS and Windows

Docker Compose is included with Docker Desktop. Simply install Docker Desktop:

# Verify installation
docker compose version

Linux

# Install Docker Compose plugin
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Verify
docker compose version

Basic Docker Compose Structure

The compose.yaml File

# compose.yaml (preferred over docker-compose.yml)
name: myapp

services:
  web:
    build: ./web
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    depends_on:
      - api
      - db

  api:
    build: ./api
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/myapp
    depends_on:
      db:
        condition: service_healthy

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

volumes:
  postgres_data:

Essential Commands

# Start all services
docker compose up

# Start in detached mode
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 specific service logs
docker compose logs -f api

# Execute command in running container
docker compose exec api sh

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

Advanced Patterns

1. Multi-Environment Configuration

# compose.yaml (base configuration)
services:
  api:
    build: ./api
    environment:
      - NODE_ENV=${NODE_ENV:-development}

# compose.override.yaml (development overrides - auto-loaded)
services:
  api:
    volumes:
      - ./api:/app
      - /app/node_modules
    command: npm run dev

# compose.prod.yaml (production overrides)
services:
  api:
    restart: always
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

# Development (uses compose.yaml + compose.override.yaml)
docker compose up

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

2. Health Checks and Dependencies

services:
  api:
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
      migrations:
        condition: service_completed_successfully

  db:
    image: postgres:16-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  migrations:
    build: ./api
    command: npm run migrate
    depends_on:
      db:
        condition: service_healthy

3. Networking Best Practices

services:
  frontend:
    networks:
      - frontend-net

  api:
    networks:
      - frontend-net
      - backend-net

  db:
    networks:
      - backend-net

networks:
  frontend-net:
  backend-net:
    internal: true  # No external access

4. Secrets Management

services:
  api:
    secrets:
      - db_password
      - api_key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  api_key:
    environment: API_KEY

Development Workflow

Hot Reload Setup

services:
  frontend:
    build: ./frontend
    volumes:
      - ./frontend/src:/app/src
    environment:
      - CHOKIDAR_USEPOLLING=true

  api:
    build: ./api
    volumes:
      - ./api/src:/app/src
      - /app/node_modules
    command: npm run dev

Debugging Configuration

services:
  api:
    ports:
      - "8080:8080"
      - "9229:9229"  # Debug port
    command: node --inspect=0.0.0.0:9229 src/index.js

Docker Compose Watch (2026 Feature)

services:
  api:
    build: ./api
    develop:
      watch:
        - action: sync
          path: ./api/src
          target: /app/src
        - action: rebuild
          path: ./api/package.json
        - action: sync+restart
          path: ./api/config
          target: /app/config

# Start with watch mode
docker compose watch

Production Considerations

Resource Limits

services:
  api:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

Logging Configuration

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

Restart Policies

services:
  api:
    restart: unless-stopped
    # Options: no, always, on-failure, unless-stopped

Common Patterns

Full-Stack Application

name: fullstack-app

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - frontend
      - api

  frontend:
    build: ./frontend
    expose:
      - "3000"

  api:
    build: ./api
    expose:
      - "8080"
    depends_on:
      - db
      - redis

  db:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

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

volumes:
  postgres_data:
  redis_data:

secrets:
  db_password:
    file: ./secrets/db_password.txt

Troubleshooting

Common Issues

# Container won't start - check logs
docker compose logs api

# Permission issues with volumes
# Add user mapping in Dockerfile or compose

# Network connectivity issues
docker compose exec api ping db

# Clean slate
docker compose down -v --remove-orphans
docker system prune -af

Conclusion

Docker Compose remains the gold standard for local development and simple production deployments in 2026. Its declarative approach, combined with powerful features like health checks, watch mode, and multi-environment support, makes it an indispensable tool for modern developers.

For larger production deployments, consider graduating to Kubernetes while keeping Docker Compose for local development consistency.

Resources

이 글이 도움이 되셨다면 공감 및 광고 클릭을 부탁드립니다 :)