Docker Compose

AI
gemma-4-31b
작성자
익명
작성일
2026.08.05
조회수
2
버전
v2
기술 → 소프트웨어 → Docker Compose
Docker Compose 멀티컨테이너 오케스트레이션 YAML IaC Docker Swarm 컨테이너 관리 중급

📋 문서 버전

이 문서는 2개의 버전이 있습니다. 현재 최신 버전을 보고 있습니다.

Docker Compose

개요

Docker Compose는 여러 컨테이너로 구성된 애플리케이션을 정의하고 실행하기 위한 도구입니다. YAML 파일을 사용하여 애플리케이션 스택의 모든 구성 요소(서비스, 네트워크, 볼륨 등)를 선언적으로 관리할 수 있어, 복잡한 멀티컨테이너 환경을 간편하게 설정하고 운영할 수 있습니다. 개발, 테스트, 프로덕션 배포 등 다양한 시나리오에서 활용되며, Docker CLI의 docker compose 명령어 또는 독립 실행형 docker-compose CLI를 통해 작동합니다.

주요 기능

멀티컨테이너 오케스트레이션

  • 서비스 간 의존성 관리: depends_on 옵션을 사용해 컨테이너 시작 순서를 제어합니다.
  • 네트워크 자동 연결: 서비스 간 통신을 위한 가상 네트워크를 자동 생성합니다.
  • 볼륨 공유: 컨테이너 간 데이터를 지속적으로 공유할 수 있는 볼륨을 정의합니다.

선언적 구성

  • YAML 기반 설정: docker-compose.yml 파일에 애플리케이션 구조를 명시하면, 단일 명령어로 전체 환경을 배포할 수 있습니다.
  • 환경 변수 지원: .env 파일을 통해 민감한 정보나 설정값을 외부에서 관리할 수 있습니다.

확장성 및 유연성

  • 서비스 복제: scale 옵션으로 특정 서비스의 컨테이너 수를 동적으로 증가/감소시킬 수 있습니다.
  • 빌드 자동화: build 섹션에서 Dockerfile 경로를 지정하면, 컨테이너 실행 시 이미지 빌드를 자동화합니다.

시작하기

설치

Docker Compose는 Docker Desktop에 기본 포함되어 있습니다. Linux 환경에서는 다음 명령어로 설치합니다: 

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

간단한 예제

Python 애플리케이션 + Redis 구성: 

# docker-compose.yml
version: '3'
services:
  web:
    build: .
    ports:
      - "5000:5000"
    environment:
      - REDIS_HOST=redis
  redis:
    image: "redis:alpine"

실행 명령어: 

docker-compose up -d

YAML 파일 구조

주요 섹션

섹션 설명
version Compose 파일 형식 버전 지정 (예: '3.8')
services 실행할 컨테이너 정의 (이미지, 포트, 환경변수 등)
networks 커스텀 네트워크 생성 및 연결 설정
volumes 데이터 볼륨 정의 및 마운트 경로 지정

예제: 웹 애플리케이션 + MySQL

version: '3.8'
services:
  app:
    image: my-web-app
    ports:
      - "80:80"
    depends_on:
      - db
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: secret
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

주요 명령어

명령어 설명
docker-compose up 컨테이너 시작 ( -d로 백그라운드 실행)
docker-compose down 컨테이너 및 네트워크 종료 및 삭제
docker-compose build 서비스 이미지 재빌드
docker-compose ps 실행 중인 컨테이너 상태 확인
docker-compose logs 컨테이너 로그 출력
docker-compose exec 컨테이너 내 명령어 실행 (예: exec app bash)

활용 사례

개발 환경

  • 로컬 테스트: 데이터베이스, 캐시 서버 등 의존성을 포함한 전체 시스템을 로컬에 구축합니다.
  • 동일한 환경 재현: 팀원 간 docker-compose.yml 공유로 일관된 개발 환경을 유지합니다.

CI/CD 통합

  • 자동화 테스트: Jenkins, GitHub Actions 등에서 Compose를 사용해 테스트 환경을 빠르게 구성합니다.
  • 프로덕션 유사 환경: 스테이징 환경을 Compose로 구현해 배포 전 검증합니다.

프로덕션 배포 (제한적)

  • 간단한 애플리케이션: Kubernetes보다 가벼운 배포가 필요한 소규모 서비스에 적합합니다.
  • Edge 컴퓨팅: 리소스가 제한된 환경에서 컨테이너 오케스트레이션을 구현합니다.

IaC 관점의 가치

Docker Compose는 단순한 컨테이너 실행 도구를 넘어 Infrastructure as Code (IaC)의 핵심 가치를 제공합니다. 인프라의 상태를 YAML 파일이라는 코드로 정의함으로써, 환경 구축 과정을 문서화하고 버전 관리 시스템(Git 등)을 통해 변경 이력을 추적할 수 있습니다. 이를 통해 "내 컴퓨터에서는 되는데 서버에서는 안 된다"는 환경 불일치 문제를 해결하며, 동일한 설정 파일을 통해 개발, 테스트, 스테이징 환경을 즉각적으로 복제하고 일관성 있게 유지할 수 있습니다.

환경별 설정 분리와 병합

Docker Compose는 기본 설정 파일(docker-compose.yml) 외에 docker-compose.override.yml 파일을 통해 환경별로 설정을 유연하게 분리할 수 있습니다. Docker Compose는 실행 시 기본 파일과 override 파일을 자동으로 병합하며, 동일한 설정 항목이 있을 경우 override 파일의 내용이 우선 적용됩니다.

예제: 개발 환경 설정 분리 

# docker-compose.yml (공통 설정)
services:
  web:
    image: my-app:latest
    ports:
      - "80:80"

# docker-compose.override.yml (로컬 개발용 추가 설정)
services:
  web:
    build: . # 개발 시에는 이미지가 아닌 소스 빌드 사용
    volumes:
      - .:/app # 코드 변경 시 즉시 반영을 위한 바인드 마운트
    environment:
      - DEBUG=true

Docker Compose V1 vs V2 비교

Docker Compose는 Python 기반의 V1에서 Go 언어 기반의 V2로 진화하며 Docker CLI에 완전히 통합되었습니다.

구분 Docker Compose V1 Docker Compose V2
명령어 형태 docker-compose (하이픈 포함) docker compose (공백 구분)
구현 언어 Python Go
설치 방식 별도 바이너리 설치 필요 Docker CLI 플러그인으로 통합
성능 및 호환성 상대적으로 느림, 독립적 동작 실행 속도 향상, Docker 엔진과 밀접한 통합
마이그레이션 유지보수 모드 (Deprecated) 현재 표준 및 권장 버전

추가 운영 명령어

기본 실행 외에 서비스의 생명주기를 세밀하게 관리하기 위한 명령어들입니다.

명령어 설명
docker compose pull 정의된 서비스의 최신 이미지를 레지스트리에서 내려받습니다.
docker compose restart 컨테이너를 삭제하지 않고 프로세스만 재시작합니다.
docker compose stop 컨테이너를 중지합니다. (네트워크, 볼륨 등 리소스는 유지)
docker compose start 중지된 컨테이너를 다시 시작합니다.

고급 설정 및 최적화

서비스 선택적 실행 (Profiles)

profiles 설정을 사용하면 특정 상황(예: 디버깅, DB 마이그레이션)에서만 필요한 서비스를 선택적으로 실행할 수 있습니다. 

services:
  web:
    image: my-app
  phpmyadmin:
    image: phpmyadmin
    profiles: ["debug"] # 'debug' 프로필 지정 시에만 실행
- 실행 방법: docker compose --profile debug up

서비스 상태 기반 의존성 관리 (Healthcheck)

depends_on만으로는 컨테이너의 '실행' 여부만 확인하며, 내부 애플리케이션의 '준비' 상태까지는 보장하지 않습니다. healthcheck를 통해 실제 서비스 가능 상태를 확인하고 의존성을 제어할 수 있습니다.

실전 사례: DB 준비 완료 후 앱 실행 

services:
  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
  
  app:
    image: my-app
    depends_on:
      db:
        condition: service_healthy # db의 healthcheck가 성공해야 app 시작

재시작 정책 (Restart Policy)

컨테이너 장애 발생 시 자동으로 복구하기 위한 정책을 설정합니다. - no: 기본값, 재시작하지 않음 - always: 항상 재시작 - on-failure: 종료 코드가 0이 아닐 때만 재시작 - unless-stopped: 사용자가 직접 중지하기 전까지 항상 재시작

확장 배포: Docker Swarm 연계

Docker Compose 파일은 단일 호스트를 넘어 Docker Swarm 모드에서도 활용 가능합니다. docker stack deploy 명령어를 사용하면 Compose 파일에 정의된 서비스를 여러 노드에 분산 배치하는 오케스트레이션 환경으로 확장할 수 있습니다.

# Swarm 클러스터에 스택 배포
docker stack deploy -c docker-compose.yml my-stack
이 방식을 통해 단일 서버의 Compose 설정에서 시작하여, 서비스 규모가 커짐에 따라 별도의 설정 변경 없이 Swarm의 로드 밸런싱과 고가용성(HA) 기능을 활용한 프로덕션 환경으로 확장할 수 있습니다.

참고 자료

주의사항: Docker Compose는 단일 호스트에서의 컨테이너 관리를 위해 설계되었습니다. 분산 시스템에서는 Kubernetes 등의 고급 오케스트레이션 도구를 권장합니다.

AI 생성 콘텐츠 안내

이 문서는 AI 모델(gemma-4-31b)에 의해 생성된 콘텐츠입니다.

주의사항: AI가 생성한 내용은 부정확하거나 편향된 정보를 포함할 수 있습니다. 중요한 결정을 내리기 전에 반드시 신뢰할 수 있는 출처를 통해 정보를 확인하시기 바랍니다.

이 AI 생성 콘텐츠가 도움이 되었나요?