[Docker Compose][profiles] 개발·디버그 서비스를 선택적으로 켜는 설정 기준

IT 리서치 노트

[Docker Compose][profiles] 개발·디버그 서비스를 선택적으로 켜는 설정 기준

Docker Compose profiles는 개발·디버그·관리 도구를 같은 compose.yaml에 두되 필요할 때만 켜는 기능이다. 2026년 9월 8일 KST 기준 profile이 없는 서비스는 항상 활성화된다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

핵심 서비스에는 profile을 붙이지 않고 선택 도구에만 붙인다. 실행 전 config --profiles와 --services로 실제 범위를 확인한다.

Docker Compose ps·logs·inspect 진단 순서와 depends_on service_healthy 설정법을 함께 보면 설정 확인 뒤 런타임 장애까지 이어서 점검할 수 있다.

2. 어디서 실제로 막히는가

핵심 DB에 profile을 붙이면 기본 up에서 누락될 수 있다. 특정 서비스를 직접 실행할 때 같은 profile 전체가 함께 시작된다고 오해하는 경우도 많다. 실패를 확인할 때는 명령이 0으로 끝났는지만 보지 않는다. 예상한 서비스 이름, 이미지 태그, 마운트 경로와 실제 출력이 일치하는지 확인하고, 다른 터미널과 CI에서도 같은 명령을 실행한다. 한쪽에서만 결과가 다르면 Compose 파일보다 실행 위치, CLI 버전, 활성 profile, shell 환경을 먼저 비교한다. 설정 변경 뒤 컨테이너가 계속 예전 값으로 뜨면 기존 컨테이너와 볼륨이 남았는지도 확인한다. 재현 기록에는 docker compose version, pwd, 사용한 -f와 --env-file, 실행 명령, 종료 코드, 핵심 출력만 남긴다.

• 실행 디렉터리와 명령 인자를 기록한다.
• 예상값과 실제 출력을 같은 표로 비교한다.
• 경고, 종료 코드, 서비스 상태를 함께 확인한다.
• 비밀값은 출력과 화면에서 제거한다.

특히 관리 UI와 마이그레이션 작업을 같은 profile로 묶으면 일회성 명령이 불필요한 장기 실행 서비스를 함께 열 수 있다. profile별 활성 목록을 확인하지 않으면 포트 충돌과 권한 확대가 뒤늦게 드러난다.

3. 실무에서 적용하는 순서

서비스를 core와 optional로 분류한다. optional에만 profiles를 지정하고 profile별 config --services 결과를 저장한다. CI에서는 --profile이나 COMPOSE_PROFILES를 명시한다. 검증은 작은 재현부터 시작한다. 복사한 최소 Compose 파일에서 관련 서비스 하나만 남기고 config -q로 문법을 확인한다. 다음으로 config 또는 config --services 출력에서 원하는 설정이 실제 모델에 포함됐는지 본다. 그 뒤 docker compose up을 실행하고 ps와 logs에서 컨테이너 상태와 변경 반영 여부를 확인한다. 실패하면 동시에 여러 값을 바꾸지 말고 환경변수, profile, watch 규칙을 하나씩 되돌린다. 성공 기준은 로컬과 CI의 렌더링 결과가 같고, 재생성한 컨테이너의 설정과 로그가 기대값을 보여 주는 것이다.

1. 현재 버전과 실행 위치를 확인한다.
2. 공식 명령으로 최종 설정을 렌더링한다.
3. 한 변수 또는 한 서비스만 바꿔 재현한다.
4. ps와 logs에서 런타임 결과를 확인한다.
5. 성공·실패 출력을 저장해 비교한다.
6. CI에 검증 명령을 추가한다.

docker compose config -q
docker compose ps
docker compose logs --tail=100

4. 공식 문서와 예시 화면으로 확인하기

profile이 적용되는 서비스 범위를 확인한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

profile이 없는 서비스는 항상 활성화되고 profile이 있는 서비스만 선택적으로 활성화된다.

api와 db 같은 핵심 서비스에는 profile을 붙이지 않는 편이 안전하다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

대상 서비스를 직접 실행할 때의 예외를 확인한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

profile 서비스를 직접 지정하면 해당 서비스의 profile은 자동 활성화된다.

같은 profile의 모든 서비스가 자동으로 켜지는 것은 아니다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

핵심과 선택 서비스를 분리한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

profile 배치 기준이다.

선택 도구만 profile로 묶는다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

Compose 파일에서 선택 서비스에만 profile을 둔다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

debugger 예제다.

depends_on 관계도 같이 검토한다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

실행 전 활성 서비스 목록을 확인한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

profile 검증 명령이다.

CI에서는 profile 값을 명시한다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

5. 주의사항과 리스크

profile은 비밀값이나 운영 설정 분리 수단이 아니다. 포트·리소스·이미지가 다르면 override 파일과 함께 설계한다.

6. 결론

profiles는 핵심 스택을 흔들지 않고 선택 도구를 붙일 때 효과적이다. 활성 서비스 목록을 명령으로 확인하면 실행 차이를 줄일 수 있다. 변경 전후의 렌더링 결과와 런타임 로그를 함께 남기면 다음 장애에서도 같은 순서로 재현할 수 있다.

7. 참고 링크

1. https://docs.docker.com/compose/how-tos/profiles/
2. https://docs.docker.com/reference/cli/docker/compose/config/