Docker Compose v2는 단순한 컨테이너 오케스트레이션을 넘어 개발 환경의 핵심 인프라로 자리잡았습니다. 2026년 현재 프로파일 기반 서비스 관리, 파일 동기화(Watch), GPU 지원, 헬스체크 의존성 등 프로덕션 수준의 기능을 제공합니다. 이 글에서는 실무에서 바로 적용할 수 있는 고급 Compose 기법을 다룹니다.

프로파일(Profiles)로 서비스 그룹 관리

프로파일을 사용하면 환경별로 필요한 서비스만 선택적으로 실행할 수 있습니다.

# docker-compose.yml
services:
  # 항상 실행되는 핵심 서비스 (프로파일 미지정)
  app:
    build: .
    ports:
      - "8080:8080"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17
    environment:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  # 개발 환경에서만 필요한 서비스
  adminer:
    image: adminer
    ports:
      - "8081:8080"
    profiles:
      - dev

  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025"
      - "8025:8025"
    profiles:
      - dev

  # 모니터링 스택
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    profiles:
      - monitoring

  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"
    profiles:
      - monitoring

  # 테스트용 서비스
  test-runner:
    build:
      context: .
      dockerfile: Dockerfile.test
    profiles:
      - test

# 프로파일 사용법
docker compose up                              # app + db만 실행
docker compose --profile dev up                # app + db + adminer + mailhog
docker compose --profile monitoring up          # app + db + prometheus + grafana
docker compose --profile dev --profile monitoring up  # 전부

# 환경 변수로 기본 프로파일 설정
export COMPOSE_PROFILES=dev,monitoring
docker compose up

Watch 모드: 핫 리로드 자동화

docker compose watch는 로컬 파일 변경을 감지하여 컨테이너를 자동 업데이트합니다. 볼륨 마운트보다 성능이 좋고, 빌드 단계를 포함한 동기화가 가능합니다.

services:
  web:
    build: .
    ports:
      - "3000:3000"
    develop:
      watch:
        # 소스 코드 변경 -> 컨테이너에 동기화
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
            - "**/*.test.js"

        # package.json 변경 -> 이미지 리빌드 + 재시작
        - action: rebuild
          path: ./package.json

        # 설정 파일 변경 -> 컨테이너만 재시작
        - action: sync+restart
          path: ./config
          target: /app/config

  api:
    build: ./api
    ports:
      - "8080:8080"
    develop:
      watch:
        - action: sync
          path: ./api/src
          target: /app/src
        - action: rebuild
          path: ./api/go.mod

# Watch 모드 실행
docker compose watch

# 백그라운드에서 실행 + 로그 표시
docker compose watch --no-up &
docker compose up -d
docker compose logs -f

의존성과 헬스체크 고급 설정

services:
  app:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true  # db 재시작 시 app도 재시작
      redis:
        condition: service_healthy
      migrations:
        condition: service_completed_successfully  # 마이그레이션 완료 후 시작

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

  db:
    image: postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 30s      # 시작 후 30초간 실패 무시
      start_interval: 2s     # 시작 기간 중 체크 간격

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

GPU 지원 (AI/ML 워크로드)

services:
  ml-training:
    image: pytorch/pytorch:2.5-cuda12.4-cudnn9-runtime
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all       # 모든 GPU 사용
              capabilities: [gpu]
    volumes:
      - ./data:/data
      - ./models:/models

  inference:
    build: ./inference
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1         # GPU 1개만
              capabilities: [gpu]
        limits:
          memory: 8G           # 메모리 제한
    ports:
      - "8000:8000"

다중 Compose 파일 오버라이드

# docker-compose.yml (기본)
services:
  app:
    image: myapp:latest
    ports:
      - "8080:8080"
    environment:
      NODE_ENV: production

# docker-compose.override.yml (자동 오버라이드)
services:
  app:
    build: .                     # 이미지 대신 빌드
    volumes:
      - ./src:/app/src           # 소스 마운트
    environment:
      NODE_ENV: development
      DEBUG: "app:*"

# docker-compose.staging.yml (별도 환경)
services:
  app:
    image: myapp:staging
    environment:
      NODE_ENV: staging
      DATABASE_URL: ${STAGING_DB_URL}

# 사용법
docker compose up                          # yml + override 자동 병합
docker compose -f docker-compose.yml \
  -f docker-compose.staging.yml up         # 스테이징 환경

# 병합 결과 미리보기
docker compose config                      # 최종 설정 출력
docker compose -f docker-compose.yml \
  -f docker-compose.staging.yml config

유용한 Compose 명령어 모음

# 서비스 상태 확인
docker compose ps -a                    # 모든 서비스 상태
docker compose top                      # 프로세스 목록
docker compose stats                    # 리소스 사용량 (실시간)

# 로그
docker compose logs -f --tail=100 app   # 특정 서비스 최근 100줄
docker compose logs --since 5m          # 최근 5분

# 실행 중인 컨테이너에 명령 실행
docker compose exec app bash            # 셸 접속
docker compose exec db psql -U postgres # DB 접속

# 일회성 명령 실행
docker compose run --rm app npm test    # 테스트 실행 후 컨테이너 삭제

# 이미지 관리
docker compose build --no-cache         # 캐시 없이 빌드
docker compose pull                     # 이미지 업데이트
docker compose push                     # 레지스트리에 푸시

# 정리
docker compose down                     # 컨테이너 중지 + 삭제
docker compose down -v                  # 볼륨까지 삭제
docker compose down --rmi all           # 이미지까지 삭제

Docker Compose v2는 단순한 개발 도구를 넘어 스테이징, 테스트, AI/ML 워크로드까지 아우르는 범용 컨테이너 관리 도구입니다. 프로파일로 환경별 서비스를 유연하게 관리하고, Watch로 개발 생산성을 높이며, 헬스체크 의존성으로 안정적인 서비스 기동을 보장하세요.