HAEJUN RECORDS

Docker Compose 개념

8 min read

Summary

  • Compose는 여러 컨테이너의 구성을 YAML 파일 하나로 선언해 관리하는 도구다.
  • services, image, ports, volumes, depends_on이 핵심 키다.
  • docker compose up과 docker compose down으로 여러 컨테이너를 한 번에 실행하고 정리할 수 있다.

들어가며

Airflow처럼 웹서버·스케줄러·DB·큐 등 여러 컨테이너가 필요한 서비스를 매번 docker run으로 따로 실행하면 번거롭고 실수하기 쉽다. Docker Compose는 여러 컨테이너의 구성을 파일 하나로 선언해 한 번에 관리하는 도구다.

Docker Compose

Compose 핵심 흐름

  • compose.yaml: 여러 서비스의 역할과 실행 설정 선언
  • service: web, db처럼 컨테이너가 맡을 역할
  • image: 서비스 실행에 사용할 템플릿
  • Docker Engine: 설정에 따라 실제 컨테이너 생성·실행

Docker Compose는 docker-compose.yaml 파일에 어떤 컨테이너를 어떤 설정과 순서로 실행할지 미리 적어두는 방식이다. 레시피북에 여러 요리의 조리법을 한 권에 모아두는 것과 비슷하다. 이 파일 하나를 사용하면 같은 구성으로 컨테이너를 실행할 수 있다.

Compose 명령어도 결국 Docker Engine에 전달되어 여러 컨테이너를 생성하고 실행한다. Windows와 Mac에서는 Docker Desktop이 제공하는 Linux 계층 위에서 Engine이 동작한다. Docker Engine과 Docker Desktop의 관계는 Docker Desktop과 Docker Engine에서 확인할 수 있다.

Compose에서 service는 컨테이너를 실행하기 위한 역할과 설정의 묶음이다. 예를 들어 web은 화면을 보여주는 역할이고, db는 데이터를 저장하는 역할이다.

각 서비스에는 사용할 이미지, 포트, 데이터 저장 위치 등을 함께 적는다. Compose가 이 설정을 Docker Engine에 전달하면, Engine이 실제 컨테이너를 만들어 실행한다. 이미지와 컨테이너의 관계는 이미지와 컨테이너 실습에서, Docker 전체 구조는 Docker의 기본 개념에서 확인할 수 있다.

Fig 1. Docker Compose의 서비스·이미지·컨테이너 관계
Fig 1. Docker Compose의 서비스·이미지·컨테이너 관계

YAML 구조

서비스 정의

웹 앱과 DB를 함께 실행하는 최소 구성은 다음과 같다.

services:
  web:
    image: my-app:1.0
    ports:
      - "8080:80"
    depends_on:
      - db
  db:
    image: postgres:16
    volumes:
      - ./pgdata:/var/lib/postgresql/data
키역할의미
services서비스 목록 관리실행할 서비스 나열 → web, db 등 서비스 이름 지정
image이미지 지정컨테이너 생성에 사용할 이미지 지정, docker pull 대상과 동일
build이미지 직접 생성Dockerfile 기준 이미지 빌드
ports포트 연결호스트 포트와 컨테이너 포트 연결 → host:container 형식
volumes데이터 연결호스트·볼륨과 컨테이너 경로 연결, 컨테이너 삭제 후에도 데이터 보존
depends_on시작 순서 설정지정한 서비스 먼저 시작, 서비스 준비 완료는 보장하지 않음

이처럼 Compose의 각 키는 docker run에서 옵션으로 하나씩 지정했던 설정을 파일 하나에 모아 선언한 것이다.

서비스 종속성과 준비 상태

이 예시에서 web은 DB가 있어야 동작하므로 db 서비스에 의존한다. depends_on은 db 컨테이너를 먼저 시작하게 하지만, 먼저 시작됐다고 바로 연결할 수 있는 것은 아니다.

depends_on의 한계

  • depends_on: DB 컨테이너의 실행 순서만 보장, 연결 가능한 상태는 보장하지 않음
  • healthcheck + condition: service_healthy: DB 준비 상태 확인 후 web 서비스 실행

DB 준비 상태 확인 설정

db:
  image: postgres:16
  healthcheck:
    test: ["CMD", "pg_isready"]
    interval: 5s
    retries: 5
web:
  depends_on:
    db:
      condition: service_healthy
  • healthcheck: 서비스 준비 상태 확인 방법 지정
  • test: pg_isready 명령으로 DB의 준비 상태 확인
  • condition: service_healthy: DB가 healthy 상태가 된 뒤 web 서비스 실행

실행

기본 명령어

Compose 명령어는 YAML 파일에 정의한 여러 서비스를 한 번에 실행하고 관리한다.

Compose 실행 명령어

docker compose up -d
docker compose down
docker compose logs -f
  • docker compose up -d: YAML에 정의한 모든 서비스를 백그라운드에서 실행한다.
  • docker compose down: 모든 서비스를 정지하고 제거한다.
  • docker compose logs -f: 전체 서비스의 로그를 실시간으로 확인한다.

컨테이너마다 run과 stop을 반복하는 대신 서비스 전체를 한 명령으로 관리할 수 있다.

Airflow 적용

Airflow의 docker-compose.yaml에도 서비스 간 실행 순서를 지정하는 depends_on이 사용된다.

Airflow 서비스 의존성 설정

services:
  airflow-scheduler:
    depends_on:
      postgres:
        condition: service_healthy

이 설정은 PostgreSQL의 상태가 healthy가 된 뒤에 airflow-scheduler를 실행한다. 실행 순서를 사람이 직접 맞추지 않고 YAML에 선언할 수 있다.

마치며

Docker Compose는 여러 컨테이너의 설정을 YAML 파일에 선언하고, docker compose up과 docker compose down으로 전체 서비스를 한 번에 관리한다. services, image, ports, volumes, depends_on은 docker run에서 사용하던 설정을 파일로 옮긴 핵심 키다.

앞서 다룬 Docker 개념과 이미지·컨테이너 명령어는 Docker의 기본 개념과 이미지와 컨테이너 실습에서 확인할 수 있다. 다음 글에서는 이 구성을 Airflow 공식 docker-compose.yaml 전체에 적용해 살펴본다.

Reference

Graph View