Docker Compose Profiles — 선택적으로 서비스를 실행하는 방법

docker-compose up을 실행하면 정의된 모든 서비스가 한꺼번에 올라온다. 개발 중에는 모니터링 스택이나 디버그 도구가 필요 없는 경우가 많은데, 매번 주석 처리하거나 별도 파일을 유지하는 방식은 번거롭다. Compose Profiles는 서비스에 레이블을 붙여 필요한 것만 선택적으로 실행하는 공식 메커니즘이다.

profiles 배열 설정

docker-compose.yml에서 각 서비스에 profiles 키를 추가한다. 배열로 여러 프로파일에 동시에 속할 수 있다.

services:
  app:
    image: my-app:latest
    ports:
      - "3000:3000"

  prometheus:
    image: prom/prometheus
    profiles:
      - monitoring

  grafana:
    image: grafana/grafana
    profiles:
      - monitoring

  debugger:
    image: busybox
    profiles:
      - debug
    command: sleep infinity

profiles 키가 없는 서비스(여기서는 app)는 항상 실행된다. profiles가 지정된 서비스는 해당 프로파일이 활성화될 때만 실행된다.

--profile 플래그로 실행

# 기본 서비스만 실행 (app만 올라옴)
docker compose up -d

# monitoring 프로파일 활성화
docker compose --profile monitoring up -d

# 여러 프로파일 동시 활성화
docker compose --profile monitoring --profile debug up -d

환경 변수 COMPOSE_PROFILES로도 지정할 수 있다.

COMPOSE_PROFILES=monitoring,debug docker compose up -d

환경별 서비스 구성 예시

실무에서는 환경에 따라 프로파일을 다르게 조합하는 패턴이 자주 쓰인다.

┌─────────────────────────────────────────────┐
│              docker-compose.yml             │
│                                             │
│  [항상 실행]        [profiles]              │
│  ┌─────────┐       ┌──────────────────────┐ │
│  │   app   │       │ monitoring           │ │
│  │   db    │       │  prometheus, grafana │ │
│  └─────────┘       ├──────────────────────┤ │
│                    │ debug                │ │
│                    │  debugger, mailhog   │ │
│                    ├──────────────────────┤ │
│                    │ test                 │ │
│                    │  test-db, seed       │ │
│                    └──────────────────────┘ │
└─────────────────────────────────────────────┘

depends_on과 함께 사용

프로파일 서비스가 다른 서비스에 의존할 때 depends_on은 그대로 작동한다.

services:
  db:
    image: postgres:16

  seed:
    image: my-seed-tool
    profiles:
      - test
    depends_on:
      - db
    command: ./run-seed.sh

seed 서비스는 test 프로파일이 활성화될 때만 시작되며, 이때 depends_on에 따라 db가 먼저 준비된 후 실행된다.

.env 파일과 연동

.env 파일에 COMPOSE_PROFILES를 설정해두면 팀원 각자가 별도 플래그 없이 원하는 환경을 유지할 수 있다.

# .env.local
COMPOSE_PROFILES=debug

# .env.ci
COMPOSE_PROFILES=test

# CI 환경에서
cp .env.ci .env
docker compose up -d

profiles는 하나의 docker-compose.yml로 개발, 테스트, 모니터링 환경을 모두 커버하면서도 불필요한 서비스를 올리지 않는 가장 깔끔한 방법이다. 별도 파일 분리(-f 플래그)보다 유지보수가 단순하고, 팀 전체가 동일한 파일을 공유할 수 있다는 점이 핵심 장점이다.