Docker Compose cheatsheet: 예시와 함께 가장 유용한 명령어

여기에는 Docker Compose 치트시트 가 포함되어 있습니다. 주석이 달린 예제를 통해 Compose 파일과 명령어를 빠르게 숙달하실 수 있도록 도움을 드립니다.

이 가이드는 개발자 도구: 현대적 개발 워크플로우 완전 가이드.의 일부입니다.

선결 조건

Compose를 사용하려면 Docker Engine이 설치되어 있어야 합니다. Ubuntu의 경우, Ubuntu에 Docker 설치하기를 참고하여 적절한 설치 방법을 선택하고 docker compose 플러그인을 설정하세요.

Compose 파일 참고: docker-compose.yml

핵심 구조:

version: '3'       # Compose 파일 형식 버전

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"   # 호스트 포트 8080:컨테이너 포트 80
  db:
    image: postgres
    environment:            # 환경 변수
      POSTGRES_PASSWORD: example
    volumes:
      - db_data:/var/lib/postgresql/data

networks:          # 사용자 지정 네트워크
  appnet:
    driver: bridge

volumes:           # 이름이 지정된 볼륨
  db_data:

• services: 멀티컨테이너 애플리케이션의 각 컨테이너를 나타냅니다. 위 예제에서는 web과 db라는 두 개의 서비스가 있습니다. 개별 컨테이너 작업에 대해서는 Docker 치트시트를 참고하세요.
• networks & volumes: 격리된 네트워크와 영구 저장소를 정의합니다 - 여기에는 appnet 네트워크와 db_data 볼륨이 있습니다.

예제

포트 매핑이 포함된 단일 서비스

services:
  app:
    build: .
    ports:
      - "8000:80"   # 호스트 포트 8000:컨테이너 포트 80

호스트 포트 8000에서 앱을 노출하고 현재 디렉토리의 Dockerfile에서 빌드합니다.

공유 볼륨 및 사용자 지정 네트워크가 포함된 멀티 서비스

version: '3'
services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - type: bind
        source: ./app
        target: /app
    networks:
      - mynet
  db:
    image: postgres
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - mynet

networks:
  mynet:

volumes:
  db_data:

Web과 DB가 같은 네트워크에 있으며, DB는 영구 저장소인 이름이 지정된 볼륨 db_data를 사용합니다.

빌드 컨텍스트 및 Dockerfile 경로 사용

docker-compose.yml에서 지정된 Dockerfile을 사용하여 온디맨드 docker 이미지 빌드할 수 있습니다.

services:
  app:
    build:
      context: .
      dockerfile: docker/MyDockerfile

서비스 간 데이터 공유

services:
  web:
    image: nginx
    volumes:
      - shared_data:/usr/share/nginx/html
  worker:
    image: myworker
    volumes:
      - shared_data:/usr/src/app/data

volumes:
  shared_data:

두 서비스 모두 동일한 볼륨(정적 파일 또는 데이터 교환용)에 액세스합니다 - shared_data.

고급 Compose 파일 옵션

• environment: 컨테이너의 ENV 변수를 설정합니다.
• depends_on: 서비스 시작 순서를 제어합니다.
• deploy.replicas: Swarm 모드에서 서비스를 확장합니다.

예제:

services:
  web:
    image: nginx
    deploy:
      replicas: 3
    depends_on:
      - db

3개의 web 인스턴스를 시작합니다; 시작 순서만 제어하며 (레디니스/readiness는 제어하지 않음).

필수 Docker Compose 명령어

일반적인 Compose 패턴

• 영구 데이터가 있는 데이터베이스

  services:
    mysql:
      image: mysql
      environment:
        MYSQL_ROOT_PASSWORD: password
      volumes:
        - mysql_data:/var/lib/mysql
  
  volumes:
    mysql_data:
  

  DB 데이터는 컨테이너 재시작 시에도 mysql_data 볼륨에 영구적으로 저장됩니다.

• 개발용 코드 바운트 마운팅(Bind mounting)

  services:
    app:
      build: .
      volumes:
        - .:/app
  

  호스트에서 코드를 라이브 편집하면 컨테이너에 자동으로 반영됩니다.

유용한 플래그

• -d: 디태치 모드(백그라운드로 실행).
• --build: 시작 전에 이미지를 강제 재빌드합니다.
• --force-recreate: 변경이 없어도 컨테이너를 재생성합니다.
• --remove-orphans: Compose 파일에 정의되지 않은 컨테이너를 제거합니다.

서비스 정의 및 사용자 지정

docker-compose.yml 파일을 활용하여 서비스, 네트워크, 볼륨을 정의하고 사용자 지정할 수 있습니다. 이 파일은 애플리케이션의 모든 구성 및 오케스트레이션 요구 사항을 중앙 집중화합니다.

• **서비스(Services)**는 services 키 아래에 정의됩니다.
• 각 서비스는 컨테이너 구성을 나타내며, 다음을 설정할 수 있습니다:
  • Image: Docker Hub 또는 다른 레지스트리에서 이미지를 선택합니다.
  • Ports: 컨테이너 포트를 호스트 포트로 매핑합니다.
  • Environment variables: 구성 값을 전달합니다.
  • Volumes: 데이터를 영구적으로 저장하거나 호스트 또는 다른 서비스와 파일/폴더를 공유합니다.
  • Networks: 서비스가 액세스할 수 있는 네트워크를 제어합니다.

예제:

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"   # 호스트 포트 8080:컨테이너 포트 80
    environment:
      - NGINX_HOST=localhost
    volumes:
      - web_data:/usr/share/nginx/html
    networks:
      - frontend

  db:
    image: postgres:13
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - backend

• 여기서 web 서비스는 nginx 이미지를 사용하며, 환경 변수를 설정하고, 볼륨을 연결하고, 호스트의 포트 80을 8080으로 노출하며, frontend 네트워크에 연결합니다. db 서비스는 PostgreSQL에 대해 비슷한 작업을 수행합니다.

네트워크 사용자 지정

• **Networks(네트워크)**는 어떤 서비스들이 통신할 수 있는지를 제어합니다. Compose는 기본 네트워크를 생성하지만, 더 많은 네트워크를 정의하고, 사용자 지정 드라이버를 지정하며, 옵션을 설정하고, 미세한 격리를 위해 어떤 서비스가 어떤 네트워크에 참여하는지 결정할 수 있습니다.
• 최상위 수준의 networks에서 네트워크를 정의하고, 서비스 수준 networks 키로 서비스가 첨부해야 할 네트워크를 나열합니다.

예제:

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"

• 네트워크를 서비스에 첨부합니다:

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

• 이 설정은 app 서비스가 frontend 및 backend 네트워크의 사용자(또는 서비스) 모두에 액세스할 수 있게 하고, db는 backend 네트워크 내에서만 액세스 가능하게 합니다.

볼륨 사용자 지정

• **Volumes(볼륨)**은 최상위 volumes 키 아래에 정의됩니다. 서비스 아래에 있는 volumes 키를 사용하여 컨테이너에 마운트합니다.
• 볼륨은 이름이 지정될 수 있고, 사용자 지정 드라이버를 사용하며, 데이터 영구 저장 및 공유를 위해 여러 서비스間で 공유될 수 있습니다.

예제:

volumes:
  web_data:                # 웹 콘텐츠용 이름이 지정된 볼륨
  db_data:                 # 데이터베이스용 이름이 지정된 볼륨

services:
  web:
    volumes:
      - web_data:/usr/share/nginx/html

  db:
    volumes:
      - db_data:/var/lib/postgresql/data

• 이 예제에서 web_data는 마운트하는 컨테이너 어디에서나 사용 가능한 영구적으로 저장됩니다. db_data는 컨테이너 재생성 시에도 데이터베이스 데이터가永远不会(영원히) 손실되지 않도록 보장합니다.
• 고급 케이스를 위해 사용자 지정 드라이버 옵션이 있는 바운트 마운트를 정의할 수 있습니다:

volumes:
  db_data:
    driver: local
    driver_opts:
      type: none
      device: /data/db_data
      o: bind

• 이 구성은 호스트 경로 /data/db_data에서 컨테이너 내로 바운트 마운트를 설정합니다.

최적 관행 요약:

• 서비스 간 통신을 위해 서비스 이름을 DNS 호스트네임으로 사용하세요.
• 액세스를 제어하기 위해 필요한 경우 서비스를 여러 네트워크에 첨부하세요.
• 영구 저장소 및 데이터 공유를 위해 이름이 지정된 볼륨을 사용하세요.
• YAML을 사용하여 모든 것을 정의하여 버전 관리 및 쉬운 배포 스크립트를 가능하게 합니다.
• 컨테이너 관리 및 시각화를 위해 Linux에 Portainer 설치하기를 고려해 보세요.

여러 Compose 파일

Docker Compose에서 복잡한 멀티 서비스 설계를 조직하기 위해 여러 Compose 파일 및 오버라이드(override) 파일을 사용할 수 있습니다. 이를 통해 모듈형, 환경별, 확장 가능한 구성을 만들 수 있습니다. 여기 그 작동 방식을 소개합니다:

1. 베이스 파일 및 오버라이드 파일 구조

• 베이스 파일 생성 (compose.yaml 또는 docker-compose.yml): 모든 공통 기본 서비스 정의를 포함합니다.
• 환경별 오버라이드 파일 추가 (예: docker-compose.override.yml, docker-compose.dev.yml, docker-compose.prod.yml).

예제 파일 구조:

/project-directory
|-- docker-compose.yml           # 기본 구성
|-- docker-compose.override.yml  # 로컬/개발 오버라이드 (자동 적용)
|-- docker-compose.prod.yml      # 프로덕션 오버라이드
|-- docker-compose.test.yml      # 테스트 오버라이드 (필요 시)

기본 구성은 핵심 서비스를 정의하고, 각 오버라이드는 특정 환경이나 경우를 위해 설정을 사용자 지정합니다.

2. 파일 오버라이드 작동 방식

• 병합(Merging): docker compose up을 실행하면, Docker Compose는 베이스 파일과 오버라이드를 순서대로 병합합니다. 후속 파일은 이전 파일의 설정을 오버라이드, 확장 또는 추가합니다.
• 필드 오버라이드: 서비스나 필드가 여러 파일에 정의된 경우, 마지막 지정된 파일의 값이 사용됩니다. 새로운 필드는 추가됩니다.

병합 예제:

• docker-compose.yml:

  services:
    web:
      image: myapp
      ports:
        - "8000:80"
  

• docker-compose.override.yml:

  services:
    web:
      environment:
        - DEBUG=true
  

• 결과: web 서비스는 기본 이미지 및 포트와 오버라이드된 DEBUG 환경 변수를 모두 사용합니다.

3. 여러 파일 사용 시 명령어

• 기본 동작: docker compose 명령을 실행할 때 파일이 존재하면 docker-compose.override.yml이 docker-compose.yml과 함께 자동으로 로드됩니다.
• 파일 수동 지정: -f 플래그를 사용하여 병합할 파일과 순서를 제어합니다:

  docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
  

  • 이는 기본 오버라이드를 무시하고 프로덕션 전용 설정을 사용합니다.

4. 실용적인 조직 전략

• 환경 분리: dev, test, prod 등 환경별로 하나의 오버라이드를 사용합니다.
• 마이크로 서비스 및 팀: 다른 서비스나 팀을 위해 구성을 별도 파일로 분리하고 필요에 따라 조합합니다.
• 기능 토글: 추가 파일을 통해 임시 필요 사항(예: 추가 로깅을 위한 compose.debug.yml)을 위해 옵션 서비스 또는 구성을 도입하거나 제거합니다.

5. 장점

• 명확성: 개별 파일이 작고 초점이 맞춰지도록 유지합니다.
• 확장성: 새 서비스, 환경 또는 설정을 쉽게 추가합니다.
• 유지보수성: 주어진 배포에 대해 관련 섹션만 변경하거나 검토합니다.

6. 예제: 환경 전환

개발:

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

프로덕션:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

각 환경은 해당 환경에 필요한 구성만 받게 되며, 모든 공유 구성은 베이스 파일에 있습니다.

여러 파일을 사용하여 복잡한 Compose 설계를 조직하고 - 오버라이드/병합 시스템을 활용하여 - 대형 멀티 서비스 Docker 애플리케이션의 모듈성, 환경별 사용자 지정 및 쉬운 확장성을 보장합니다.

단일 Linux 호스트에서의 프로덕션 배포(부팅 시 시작, 깨끗한 종료, 업데이트, 로그 로테이션)에 대해서는 systemd를 사용하여 Docker Compose를 Linux 서비스로 실행하기를 참고하세요. Podman Quadlet와의 비교를 위해서는 Linux 서비스를 위한 Podman Quadlet vs Docker Compose를 확인하세요.

유용한 링크

• https://docs.docker.com/compose/
• Docker 치트시트
• Kubernetes 치트시트
• docker화된 Flutter 빌드와 Nginx를 사용한 Flutter Web 앱 Docker화
• Linux에 Portainer 설치하기
• Gitea 서버 백업 및 복원