Reference

Opening reference

Preparing the article, table of contents, and metadata. 본문, 목차, 메타데이터를 준비하고 있습니다.

Loading category cards

Preparing references and filters for this topic. 이 주제의 레퍼런스와 필터를 준비하고 있습니다.

DockerCompose와 멀티컨테이너

Compose profiles 기본

선택적 서비스 기동을 위한 Compose profiles 기능의 기본 목적과 사용 흐름을 정리합니다.

마지막 수정 2026년 4월 2일

빠른 흐름

yaml

services:
  app:
    build: .           # profile 없음 → 항상 실행

  adminer:
    image: adminer
    profiles:
      - debug          # --profile debug 할 때만 실행

  prometheus:
    image: prom/prometheus
    profiles:
      - monitoring     # --profile monitoring 할 때만 실행

bash

# 기본 서비스만 실행
docker compose up -d

# debug 프로파일 포함
docker compose --profile debug up -d

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

설정 흐름

어떤 Compose 프로파일 기준을 먼저 떠올리면 되나

상황	먼저 떠올릴 선택
항상 필요한 핵심 서비스	profile 없이 기본 실행
가끔만 필요한 보조 도구	`profiles`
여러 선택 기능을 조합해 실행	`--profile` 반복 또는 `COMPOSE_PROFILES`
현재 최종 활성 서비스 확인	`docker compose config`

프로파일 없는 서비스는 항상 실행된다 — 핵심 서비스를 기본으로 유지하는 원칙

profiles 키가 없는 서비스는 docker compose up만 해도 항상 시작됩니다. profiles에 이름을 지정한 서비스는 해당 프로파일을 명시하지 않으면 시작되지 않습니다. 이 규칙 덕분에 앱과 DB 같은 핵심 서비스는 기본으로 두고, 보조 도구만 프로파일로 분리할 수 있습니다.

yaml

services:
  app:
    build: .
    # profile 없음 → 항상 포함

  db:
    image: postgres:16
    # profile 없음 → 항상 포함

  mailhog:
    image: mailhog/mailhog
    profiles:
      - tools          # docker compose --profile tools up 해야 실행됨

--profile 플래그와 COMPOSE_PROFILES 환경변수 — 두 가지 방식으로 프로파일을 활성화한다

CLI에서는 --profile 플래그로, 환경 파일에서는 COMPOSE_PROFILES 변수로 활성화할 프로파일을 지정합니다. .env 파일에 COMPOSE_PROFILES=debug,tools처럼 적어 두면 매번 플래그를 입력하지 않아도 됩니다. 이 방식은 개발자 개인 설정을 .env 파일로 관리할 때 편리합니다.

bash

# CLI 플래그 방식
docker compose --profile debug up -d

# 환경변수 방식 (.env 파일)
echo "COMPOSE_PROFILES=debug,tools" >> .env
docker compose up -d   # debug와 tools 프로파일이 자동 활성화

profiles와 override 파일은 해결하는 문제가 다르다

profiles는 "어떤 서비스를 켤지"를 고르는 기능이고, override 파일은 "같은 서비스 설정을 어떻게 바꿀지"를 고르는 기능입니다. Adminer 같은 보조 서비스를 선택적으로 띄우는 건 profiles가 맞고, app 서비스에 개발용 bind mount나 디버그 포트를 덧붙이는 건 override 파일이 더 맞습니다.

yaml

# 선택적 서비스는 profiles
services:
  adminer:
    image: adminer
    profiles: [tools]

# 같은 app 서비스의 개발 설정은 override 파일에서 조정

실전 활용 — tools, monitoring, debug 프로파일로 선택적 구성을 나눈다

프로파일은 개발 팀이 공통으로 쓰는 Compose 파일에서 "항상 필요한 것"과 "상황에 따라 필요한 것"을 명확히 구분하는 도구입니다. DB 관리 UI, 메일 테스트 서버, 모니터링 스택처럼 선택적으로 필요한 서비스를 프로파일로 묶어 기본 실행 구성을 가볍게 유지합니다.

yaml

services:
  app:
    build: .

  db:
    image: postgres:16

  # 개발 편의 도구
  adminer:
    image: adminer
    ports:
      - "8080:8080"
    profiles: [tools]

  # 개발용 메일 서버
  mailhog:
    image: mailhog/mailhog
    profiles: [tools]

  # 모니터링 스택
  prometheus:
    image: prom/prometheus
    profiles: [monitoring]

  grafana:
    image: grafana/grafana
    profiles: [monitoring]

체크포인트

상황	적합한 선택
항상 실행되어야 하는 핵심 서비스	profiles 지정 없이 정의
가끔만 필요한 보조 도구	profiles로 그룹화
여러 프로파일을 동시에 활성화	--profile 플래그 반복 또는 COMPOSE_PROFILES
개인 개발 편의 프로파일 설정	.env 파일에 COMPOSE_PROFILES 지정
어떤 서비스가 활성화됐는지 확인	docker compose config

주의할 점

핵심 서비스까지 프로파일로 분리하면 팀원이 어떤 조합으로 실행해야 하는지 파악하기 어려워진다. 프로파일은 "항상 필요한 것"이 아닌 "선택적 보조 서비스"에만 사용해야 하며, 사용 가능한 프로파일 목록과 의도를 README나 주석으로 명시해두는 것이 중요하다.

yaml

services:
  app:
    build: .
    profiles: [dev]

bash

docker compose up -d
# dev 프로파일을 켜지 않으면 app이 아예 시작되지 않음

참고 링크

1 sources

Docker Docs: Using profiles with Compose

Reference

Opening reference

Preparing the article, table of contents, and metadata. 본문, 목차, 메타데이터를 준비하고 있습니다.

DockerCompose와 멀티컨테이너

Compose profiles 기본

선택적 서비스 기동을 위한 Compose profiles 기능의 기본 목적과 사용 흐름을 정리합니다.

마지막 수정 2026년 4월 2일

빠른 흐름

yaml

services:
  app:
    build: .           # profile 없음 → 항상 실행

  adminer:
    image: adminer
    profiles:
      - debug          # --profile debug 할 때만 실행

  prometheus:
    image: prom/prometheus
    profiles:
      - monitoring     # --profile monitoring 할 때만 실행

bash

# 기본 서비스만 실행
docker compose up -d

# debug 프로파일 포함
docker compose --profile debug up -d

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

설정 흐름

어떤 Compose 프로파일 기준을 먼저 떠올리면 되나

상황	먼저 떠올릴 선택
항상 필요한 핵심 서비스	profile 없이 기본 실행
가끔만 필요한 보조 도구	`profiles`
여러 선택 기능을 조합해 실행	`--profile` 반복 또는 `COMPOSE_PROFILES`
현재 최종 활성 서비스 확인	`docker compose config`

프로파일 없는 서비스는 항상 실행된다 — 핵심 서비스를 기본으로 유지하는 원칙

yaml

services:
  app:
    build: .
    # profile 없음 → 항상 포함

  db:
    image: postgres:16
    # profile 없음 → 항상 포함

  mailhog:
    image: mailhog/mailhog
    profiles:
      - tools          # docker compose --profile tools up 해야 실행됨

--profile 플래그와 COMPOSE_PROFILES 환경변수 — 두 가지 방식으로 프로파일을 활성화한다

bash

# CLI 플래그 방식
docker compose --profile debug up -d

# 환경변수 방식 (.env 파일)
echo "COMPOSE_PROFILES=debug,tools" >> .env
docker compose up -d   # debug와 tools 프로파일이 자동 활성화

profiles와 override 파일은 해결하는 문제가 다르다

yaml

# 선택적 서비스는 profiles
services:
  adminer:
    image: adminer
    profiles: [tools]

# 같은 app 서비스의 개발 설정은 override 파일에서 조정

실전 활용 — tools, monitoring, debug 프로파일로 선택적 구성을 나눈다

yaml

services:
  app:
    build: .

  db:
    image: postgres:16

  # 개발 편의 도구
  adminer:
    image: adminer
    ports:
      - "8080:8080"
    profiles: [tools]

  # 개발용 메일 서버
  mailhog:
    image: mailhog/mailhog
    profiles: [tools]

  # 모니터링 스택
  prometheus:
    image: prom/prometheus
    profiles: [monitoring]

  grafana:
    image: grafana/grafana
    profiles: [monitoring]

체크포인트

상황	적합한 선택
항상 실행되어야 하는 핵심 서비스	profiles 지정 없이 정의
가끔만 필요한 보조 도구	profiles로 그룹화
여러 프로파일을 동시에 활성화	--profile 플래그 반복 또는 COMPOSE_PROFILES
개인 개발 편의 프로파일 설정	.env 파일에 COMPOSE_PROFILES 지정
어떤 서비스가 활성화됐는지 확인	docker compose config

주의할 점

yaml

services:
  app:
    build: .
    profiles: [dev]

bash

docker compose up -d
# dev 프로파일을 켜지 않으면 app이 아예 시작되지 않음

참고 링크

1 sources

Docker Docs: Using profiles with Compose