docker-compose.yml은 여러 컨테이너를 하나의 파일로 정의하고 함께 실행하기 위한 선언형 설정 파일이다. YAML 포맷을 사용하며, 들여쓰기 하나로 계층 관계가 결정되기 때문에 문법을 정확히 이해하는 것이 필수다.
Compose 파일은 세 가지 최상위 키를 중심으로 구성된다.
docker-compose.yml
│
├── version ← Compose 파일 스펙 버전
├── services ← 컨테이너 정의 (필수)
├── networks ← 사용자 정의 네트워크
└── volumes ← 영속 볼륨 선언
services 가 유일하게 필수 키이며, 나머지는 필요할 때만 작성한다.
version: "3.9"
version은 어떤 Compose 스펙을 따를지 선언한다. Compose V2(Docker CLI 통합 버전)에서는 이 필드가 사실상 무시되지만, 팀 환경에서 명시적으로 남겨두는 관례가 여전히 많다.
Compose V2 — docker-compose 명령 대신 docker compose(공백)로 실행하는 Docker CLI 내장 버전. 2023년 이후 기본값.
각 서비스는 하나의 컨테이너에 대응한다.
services:
web:
image: nginx:alpine
ports:
- "80:80"
depends_on:
- db
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: secret
volumes:
- db-data:/var/lib/postgresql/data
| 키 | 역할 |
|---|---|
image | 사용할 Docker 이미지 |
build | Dockerfile 경로로 직접 빌드 |
ports | 호스트:컨테이너 포트 매핑 |
environment | 환경변수 주입 |
depends_on | 시작 순서 의존성 |
volumes | 볼륨 또는 바인드 마운트 |
들여쓰기는 스페이스 2칸 또는 4칸을 일관되게 사용해야 한다. 탭 문자는 YAML 스펙에서 금지된다.
# 문자열 — 따옴표 없이도 되지만, 특수문자 포함 시 따옴표 필요
name: my-app
label: "app:v1"
# 배열 — 블록 시퀀스
ports:
- "8080:80"
- "443:443"
# 맵(객체) — 키-값 쌍
environment:
NODE_ENV: production
PORT: "3000"
블록 시퀀스(Block Sequence) — -(하이픈)으로 각 항목을 나열하는 YAML 배열 표현 방식.
멀티라인 문자열이 필요하면 |(개행 유지) 또는 >(개행을 공백으로 접기)를 사용한다.
command: |
sh -c "
python manage.py migrate &&
python manage.py runserver 0.0.0.0:8000
"
서비스 내부에서 참조하는 named volume과 network는 최상위에도 선언해야 한다.
volumes:
db-data: # 이름만 선언하면 Docker가 관리
networks:
backend:
driver: bridge
선언 없이 서비스에서 참조하면 Compose가 자동 생성하지만, 명시적으로 선언하면 드라이버 옵션이나 외부 볼륨 연결(external: true) 같은 세부 설정이 가능하다.
external: true — Compose 외부에서 미리 생성된 볼륨 또는 네트워크를 참조할 때 사용. Compose가 해당 리소스를 생성하거나 삭제하지 않는다.