[Docker] Docker Compose: 다중 컨테이너 애플리케이션 관리하기

Docker Compose에 대해 자세히 알아보겠습니다. Docker Compose는 여러 개의 컨테이너를 효율적으로 관리하고 운영할 수 있게 도와주는 강력한 도구입니다. 단일 파일(docker-compose.yaml)을 통해 이미지 빌드, 컨테이너 실행, 볼륨 및 네트워크 생성 등을 간편하게 설정할 수 있습니다. 이 글에서는 Docker Compose의 기본 개념부터 실습 예제까지 단계별로 설명하겠습니다.

---

Docker Compose란?

Compose file reference

 

Docker Compose는 다중 컨테이너 Docker 애플리케이션을 정의하고 실행할 수 있는 도구입니다. YAML 형식의 파일(docker-compose.yaml)을 사용하여 애플리케이션의 서비스, 네트워크, 볼륨 등을 선언적으로 정의할 수 있습니다. 이를 통해 복잡한 애플리케이션 스택을 단순화하고, 일관된 환경을 유지할 수 있습니다.

주요 특징

• 간편한 설정: YAML 파일을 통해 여러 컨테이너의 설정을 한 곳에서 관리할 수 있습니다.
• 일괄 관리: 단일 명령어로 모든 컨테이너를 빌드, 시작, 중지, 삭제할 수 있습니다.
• 환경 일관성: 개발, 테스트, 프로덕션 환경에서 동일한 설정을 사용할 수 있습니다.
• 의존성 관리: 서비스 간의 의존성을 정의하여 올바른 순서로 컨테이너를 시작할 수 있습니다.

---

Docker Compose의 주요 기능

• 이미지 빌드: docker-compose.yaml 파일 내에서 빌드할 이미지를 정의할 수 있습니다.
• 컨테이너 실행: 여러 컨테이너를 동시에 실행하고 관리할 수 있습니다.
• 볼륨 및 네트워크 관리: 필요한 볼륨과 네트워크를 자동으로 생성하고 연결할 수 있습니다.
• 서비스 간 의존성: 서비스 간의 의존성을 정의하여 올바른 순서로 실행할 수 있습니다.
• 환경 변수 관리: 환경 변수를 파일이나 외부 소스에서 로드하여 사용할 수 있습니다.

---

Docker Compose 설치하기

Docker Compose는 Docker Desktop에 포함되어 있어 별도의 설치가 필요 없습니다. 다만, Linux 환경에서는 별도로 설치해야 할 수도 있습니다. 설치 방법은 아래의 공식 문서를 참고하세요.

docker compose

설치 확인

docker compose version

예시 출력

Docker Compose version v2.20.3

---

Docker Compose 기본 사용법

Docker Compose를 사용하기 위해서는 docker-compose.yaml 파일을 작성해야 합니다.
이 파일에 애플리케이션의 모든 서비스를 정의하고, Docker Compose 명령어를 통해 이를 관리할 수 있습니다.

Compose 파일 구조

Compose 파일은 YAML 형식으로 작성되며, 주로 다음과 같은 구조를 가집니다.

version: '3.8' # Compose 파일 버전

services: # 서비스 정의
  service_name: # 서비스 이름
    image: image_name # 사용할 Docker 이미지
    build: # 이미지 빌드 설정 (선택 사항)
      context: ./path # 빌드 컨텍스트
      dockerfile: Dockerfile # 사용할 Dockerfile
      args: # 빌드 인수
        - ARG_NAME=value
    container_name: container_name # 컨테이너 이름 (선택 사항)
    environment: # 환경 변수 설정
      - VAR_NAME=value
    ports: # 포트 매핑
      - "host_port:container_port"
    volumes: # 볼륨 마운트
      - volume_name:/container/path
    networks: # 네트워크 연결
      - network_name
    depends_on: # 서비스 의존성
      - other_service

networks: # 네트워크 정의
  network_name:
    driver: bridge

volumes: # 볼륨 정의
  volume_name:
    driver: local

컨테이너 빌드 및 실행

Compose 파일을 작성한 후, 다음 명령어를 통해 모든 서비스를 빌드하고 실행할 수 있습니다.

docker compose up

백그라운드 실행

백그라운드에서 컨테이너를 실행하려면 -d 옵션을 사용합니다.

docker compose up -d

컨테이너 관리

Docker Compose를 사용하면 여러 컨테이너를 손쉽게 관리할 수 있습니다. 주요 명령어는 다음과 같습니다.

• 실행 및 빌드: docker compose up --build
• 중지 및 삭제: docker compose down
• 로그 확인: docker compose logs -f
• 특정 서비스 실행: docker compose up -d service_name

---

Example) MySQL과 애플리케이션 연동하기

Docker Compose를 사용하여 MySQL 데이터베이스와 애플리케이션을 연동하는 예제를 실습해보겠습니다.

프로젝트 준비

먼저, 프로젝트 디렉토리를 생성하고 필요한 파일을 준비합니다.

mkdir mbti-docker-compose
cd mbti-docker-compose

docker-compose.yaml 파일 작성

아래 예제는 애플리케이션과 MySQL 데이터베이스를 정의한 docker-compose.yaml 파일입니다.

version: '3.8'

name: mbti # 지정하지 않으면 디렉토리 이름으로 지정됨

services:
  app: # 애플리케이션 컨테이너
    image: daehyunbigbread/mbti:mysql
    build:
      args:
        - NODE_VERSION=20.15.1
      dockerfile: ./Dockerfile
      pull: true
      context: .
    container_name: app
    environment:
      - PORT=3000
      - DB_HOST=db
      - DB_PORT=3306
      - DB_NAME=db_mbti
      - DB_USERNAME=user_mbti
      - DB_PASSWORD=pw_mbti
    networks:
      - mbti-net
    ports:
      - "4000:3000"
    depends_on:
      - db

  db: # MySQL 데이터베이스 컨테이너
    image: mysql:8.3.0
    container_name: db
    environment:
      - MYSQL_ROOT_PASSWORD=pw_root
      - MYSQL_DATABASE=db_mbti
      - MYSQL_USER=user_mbti
      - MYSQL_PASSWORD=pw_mbti
    networks:
      - mbti-net
    volumes:
      - mbti-vol:/var/lib/mysql

networks:
  mbti-net:
    name: mbti-net

volumes:
  mbti-vol:
    name: mbti-vol

Docker Compose로 서비스 실행

docker-compose.yaml 파일이 위치한 디렉토리에서 다음 명령어를 실행하여 서비스를 빌드하고 실행합니다.

docker compose up --build -d

실행 결과

[+] Building 2.1s (10/10) FINISHED
[+] Running 2/4
 ✔ Network mbti-net   Created
 ✔ Volume mbti-vol    Created
 ✔ Container db       Started
 ✔ Container app      Started

---

서비스 간 의존성 설정

Control startup order

 

Compose 파일에서 depends_on 옵션을 사용하여 서비스 간의 의존성을 설정할 수 있습니다. 위 예제에서는 app 서비스가 db 서비스에 의존하도록 설정하였습니다. 이는 app 서비스가 db 서비스가 시작된 후에 실행되도록 보장합니다.

참고: depends_on은 컨테이너의 시작 순서만 보장하며, 서비스가 완전히 준비되었는지 확인하지는 않습니다.
서비스의 준비 상태를 확인하려면 healthcheck를 추가해야 합니다.

services:
  app:
    # ...
    depends_on:
      db:
        condition: service_healthy

  db:
    # ...
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 3

 

---

Docker Compose 주요 명령어

Docker Compose를 효과적으로 사용하기 위해 알아두면 좋은 주요 명령어들을 소개합니다.

docker compose up	Compose 파일에 정의된 모든 서비스를 빌드하고 실행합니다.
docker compose up -d	백그라운드에서 서비스를 실행합니다.
docker compose down	모든 서비스를 중지하고 컨테이너, 네트워크, 볼륨을 삭제합니다.
docker compose build	Compose 파일에 정의된 모든 서비스를 빌드합니다.
docker compose logs	서비스의 로그를 확인합니다.
docker compose restart	모든 서비스를 재시작합니다.
docker compose stop	모든 서비스를 중지합니다.
docker compose start	중지된 서비스를 시작합니다.
docker compose exec [service]	실행 중인 서비스의 컨테이너 내부에서 명령어를 실행합니다.
docker compose ps	현재 실행 중인 서비스의 상태를 확인합니다.
docker compose pull	Compose 파일에 정의된 모든 서비스의 이미지를 가져옵니다.
docker compose push	Compose 파일에 정의된 모든 서비스의 이미지를 푸시합니다.

---

추가 팁 및 주의사항

Docker Compose를 효과적으로 활용하기 위해 몇 가지 팁과 주의사항을 알아두면 좋습니다.

1. 환경 변수 파일 활용

여러 환경 변수를 관리할 때는 .env 파일을 사용하여 환경 변수를 정의하고, Compose 파일에서 이를 참조할 수 있습니다.

• .env 파일 예시:

PORT=3000
DB_HOST=db
DB_PORT=3306
DB_NAME=db_mbti
DB_USERNAME=user_mbti
DB_PASSWORD=pw_mbti
MYSQL_ROOT_PASSWORD=pw_root
MYSQL_DATABASE=db_mbti
MYSQL_USER=user_mbti
MYSQL_PASSWORD=pw_mbti

• docker-compose.yaml 파일에서 참조:

environment:
  - PORT=${PORT}
  - DB_HOST=${DB_HOST}
  - DB_PORT=${DB_PORT}
  - DB_NAME=${DB_NAME}
  - DB_USERNAME=${DB_USERNAME}
  - DB_PASSWORD=${DB_PASSWORD}

2. 볼륨과 네트워크 관리

Compose 파일 내에서 볼륨과 네트워크를 정의하여, 서비스 간의 데이터 공유와 네트워크 통신을 손쉽게 설정할 수 있습니다.

3. 서비스 스케일링

Compose 파일을 사용하면 동일한 서비스를 여러 개로 스케일링할 수 있습니다. 단일 호스트 환경에서만 가능하며, 분산 환경에서는 Docker Swarm이나 Kubernetes와 같은 도구를 사용해야 합니다.

docker compose up --scale app=3 -d

4. 빌드 캐시 활용

이미지가 이미 빌드된 경우, docker compose build 명령어는 변경된 부분만 다시 빌드하여 빌드 시간을 단축시킬 수 있습니다.

5. Healthcheck 설정

서비스가 완전히 시작되었는지 확인하기 위해 healthcheck를 설정할 수 있습니다. 이는 의존성이 있는 서비스의 안정적인 시작을 보장하는 데 도움이 됩니다.

services:
  db:
    image: mysql:8.3.0
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 3

6. Compose 파일 버전 관리

Compose 파일의 버전을 적절히 관리하여 Docker의 최신 기능을 활용하고, 호환성을 유지하세요. 현재는 version: '3.8'이 많이 사용됩니다.

---

참고 자료

• Docker Compose 공식 문서: https://docs.docker.com/compose/
• Compose 파일 참조: Compose file reference
• Docker CLI Reference - Compose: Docker Compose Commands
• MySQL Docker 이미지: MySQL Docker Hub
• BusyBox 공식 문서: BusyBox
• Docker Networking Best Practices: Networking Best Practices
• Docker Bind Mounts vs Volumes: Bind Mounts vs Volumes