Docker Compose 소개

Docker Compose는 여러 컨테이너로 이루어진 애플리케이션을 하나의 YAML 파일로 정의하고 실행하는 도구입니다. 웹 서버, 애플리케이션, DB, 캐시처럼 함께 떠야 하는 서비스를 compose.yaml에 묶어 관리할 수 있습니다.

현재 기준으로는 legacy docker-compose 명령보다 Docker CLI 플러그인 형태의 docker compose를 우선 사용합니다. Compose Specification에서는 예전처럼 top-level version을 반드시 쓸 필요가 없습니다.

버전 확인

docker version
docker compose version
docker compose help

compose.yaml 예시

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    restart: unless-stopped

  redis:
    image: redis:7
    restart: unless-stopped
    volumes:
      - redis-data:/data

volumes:
  redis-data:

services는 컨테이너 정의, ports는 호스트 포트 노출, volumes는 데이터 보존, restart는 컨테이너 재시작 정책을 뜻합니다.

실행과 확인

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100
docker compose logs -f web

docker compose config는 실제 해석된 Compose 모델을 보여줍니다. 운영 반영 전 YAML 들여쓰기나 변수 치환 오류를 확인하는 데 유용합니다.

서비스 명령 실행

docker compose exec web sh
docker compose restart web
docker compose pull
docker compose up -d --remove-orphans

pull 후 up -d를 실행해야 새 이미지로 컨테이너가 교체됩니다. 이미지 태그가 같아도 실제 digest가 달라질 수 있으므로 배포 기록에는 image digest를 남기는 것이 좋습니다.

환경 변수 파일

services:
  app:
    image: registry.example.com/app:2026.06.23
    env_file:
      - .env
    environment:
      APP_ENV: production

.env는 편리하지만 민감정보를 그대로 Git에 올리기 쉽습니다. password, token, API key는 repository 밖 secret store나 배포 시스템에서 주입하는 방식으로 관리합니다.

헬스체크

services:
  web:
    image: nginx:1.27
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 5s
      retries: 3

헬스체크는 컨테이너 프로세스가 살아 있는지뿐 아니라 애플리케이션이 실제 응답하는지 확인하는 기준입니다. 단, 헬스체크 명령에 필요한 도구가 이미지 안에 있어야 합니다.

종료와 정리

docker compose stop
docker compose down
docker compose down --remove-orphans
docker compose down -v

down -v는 named volume까지 삭제할 수 있습니다. DB나 업로드 데이터가 있는 Compose 프로젝트에서는 백업과 삭제 대상을 먼저 확인합니다.

운영 기준

• 프로젝트별 디렉터리와 compose.yaml을 Git으로 관리합니다.
• volume 백업/복구 절차를 Compose 파일과 별도로 문서화합니다.
• 개발용 포트 노출을 운영에 그대로 가져오지 않습니다.
• 여러 Compose 파일을 합칠 때는 docker compose config 출력으로 최종 모델을 확인합니다.

공식 문서

• Docker Compose
• Compose file reference
• How Compose works