Docker Compose 패턴

단일 호스트에서 여러 컨테이너 (웹 · DB · 캐시 · 큐) 를 함께 띄울 때 가장 가벼운 길이 Compose. YAML 한 파일로 의존 · 네트워크 · 볼륨 · 헬스체크를 묶음. 본격 오케스트레이터가 아니라는 점이 강점이자 한계. 이 글은 Compose 의 v1 vs v2 차이 · compose.yaml 핵심 키 · healthcheck · env_file · profiles · override 패턴.

1. Compose 에 대한 이야기

Compose 는 원래 Fig 라는 외부 도구 (2014) 였다가 Docker 가 인수해 흡수. v1 은 Python 으로 작성된 별도 CLI (docker-compose), v2 (2021) 부터 Go 로 재작성되어 docker compose 서브커맨드로 통합. v2 는 BuildKit · 프로필 · 더 빠른 실행이 차이.

권장 파일명은 compose.yaml 또는 compose.yml. 이전 관례인 docker-compose.yml 도 인식.

2. 기본 구조

services:
  web:
    build: ./web
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      DATABASE_URL: postgres://app:${DB_PASS}@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${DB_PASS}
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  db-data:

3. 핵심 키

4. 의존과 헬스체크

depends_on 만으로는 "다른 서비스가 살아 있다" 보장이 약함. 네트워크가 떴다 해도 DB 가 실제 쿼리 받을 준비 안 됐을 수 있음. v2 에서는 condition: service_healthy 와 healthcheck 결합으로 진짜 준비 상태 확인.

5. env_file 과 ${VAR} 치환

services:
  web:
    env_file: .env
    environment:
      LOG_LEVEL: ${LOG_LEVEL:-info}

env_file 은 컨테이너 안의 환경변수로 주입. ${VAR} 치환은 Compose 가 .env 파일과 셸 환경에서 읽어 YAML 자체를 채움. 두 자리는 의미가 다름 — 하나는 컨테이너 환경, 하나는 Compose 파일의 텍스트 치환.

6. profiles

특정 환경에서만 띄우고 싶은 서비스에 프로필을 붙임:

services:
  app: { ... }
  pgadmin:
    image: dpage/pgadmin4
    profiles: ["dev"]

docker compose --profile dev up 으로 dev 프로필 서비스까지 함께. 운영에서 불필요한 도구를 자연스럽게 빼는 데 유용.

7. override 파일

compose.yaml 옆의 compose.override.yaml 은 자동 병합. 환경별 분기에는 명시적 파일을 쓰는 편이 명확:

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

뒤에 오는 파일이 앞을 덮어씀. 개발 / 스테이징 / 운영 차이를 작은 패치 파일로 분리하는 패턴이 흔합니다.

8. extends

다른 파일의 서비스 정의를 상속 · 합성. 큰 모노레포에서 공통 베이스를 정의하는 자리:

services:
  app:
    extends:
      file: common.yaml
      service: app-base

9. 다른 길

Compose 와 비교 대상은 단일 호스트 한정.

• systemd unit + Docker — 서비스 정의를 systemd 가 관리. 의존 그래프는 systemd 의 After= · Requires=.
• Podman + quadlet — Podman 의 systemd 통합. *.container 파일에서 컨테이너 정의.
• Nomad (HashiCorp) — 단일 바이너리의 가벼운 오케스트레이터. 단일 호스트 ~ 수백 노드.
• Kubernetes — 다른 무게 클래스. 단일 호스트에 쓰면 운영 비용이 과하다는 평.

여러 호스트로 나가는 순간 Compose 는 부족. Swarm · Nomad · k8s 로 옮김.

10. 단일 호스트 적합성

장점 — 학습 비용 작음, 단일 파일에 모든 정의, 빠른 시작 / 종료.

한계 — 단일 호스트 (수평 확장 없음). 무중단 배포는 외부 도구나 수동 절차 필요. 시크릿 관리 · 롤링 업그레이드 약함.

대다수 사이드 프로젝트 · 중소 서비스는 단일 호스트 + Compose 로 충분.

11. 자주 쓰는 모양

빌드와 이미지 분리:

services:
  app:
    image: ghcr.io/my/app:1.4.2
    build: ./app

CI 에서 docker compose build 후 push. 운영 호스트에서는 pull. image 와 build 를 함께 두면 두 흐름이 자연스럽게 합쳐짐.

로깅 · 재시작 — 기본 로그 드라이버의 디스크 무한 증가 방지:

services:
  app:
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"

YAML anchor 로 일괄 적용 — 같은 logging 블록을 모든 service 에 매번 적기 보다 anchor 한 곳에서 정의하고 참조:

x-logging: &default-logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  web:
    logging: *default-logging
  db:
    logging: *default-logging

x- 접두사는 Compose 의 "확장 필드" — Compose 가 무시하지만 YAML 파서는 anchor 로 인식. 정책 변경의 단일 지점. 무설정 시 json-file 기본이 무제한 누적되므로, anchor 없이 시작해도 결국 모든 service 에 동일 블록을 붙이게 됨. 처음부터 anchor 가 깔끔.

12. 자주 걸리는 자리

포트 바인딩 주소 누락 — "8080:8080" 은 0.0.0.0 에 바인딩되어 외부 접근 가능. 운영 보안 모델에서는 "127.0.0.1:8080:8080" 이 적절할 때가 많음.

depends_on 만으로 충분하다는 오해 — condition 없이는 단순 시작 순서만 보장.

볼륨 vs 바인드 마운트의 권한 — 호스트 사용자 (uid) 와 컨테이너 사용자가 다르면 쓰기 실패가 자주.

.env 파일의 보안 — Compose 의 ${VAR} 치환을 위해 평문으로 저장. 시크릿은 별도 도구 (Docker secret · age · sops) 로 분리.

이름 충돌 — 같은 호스트에서 여러 Compose 프로젝트를 돌릴 때 프로젝트 이름이 같으면 컨테이너 · 네트워크가 섞임. --project-name 또는 디렉터리 분리.

하고픈 말

Compose 는 단일 호스트의 모든 자리를 단일 YAML 로 묶는 가장 직관적인 도구. healthcheck + condition: service_healthy + 127.0.0.1 바인딩 + override 파일 분기 네 자리가 함께 있을 때 운영의 안정성이 크게 좋아집니다.

Next

• caddy-not-nginx
• loopback-ssh-tunnel

Compose 공식 문서 · Compose Specification · Compose 파일 레퍼런스 · Healthcheck 문서 · Profiles 문서 · Podman + quadlet 을 참고합니다.