[Docker Compose][환경변수] config와 config --environment 차이로 치환 오류 찾는 법

IT 리서치 노트

[Docker Compose][환경변수] config와 config --environment 차이로 치환 오류 찾는 법

Docker Compose 환경변수 오류는 .env 파일만 열어 봐서는 원인을 놓치기 쉽다. 2026년 9월 8일 KST 기준 공식 문서에서 docker compose config는 최종 모델을, config --environment는 interpolation 입력을 보여 준다.

목차

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

1. 개요

config --environment로 치환 입력을 확인한 뒤 config로 최종 모델을 확인한다. 두 출력은 서로 다른 질문에 답한다.

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

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

로컬과 CI의 image tag가 다르거나 --env-file을 줬는데 shell 값이 이기는 증상이 흔하다. Compose는 shell, --env-file, project .env에 우선순위를 적용하며 실행 위치에 따라 읽는 파일도 달라질 수 있다. 실패를 확인할 때는 명령이 0으로 끝났는지만 보지 않는다. 예상한 서비스 이름, 이미지 태그, 마운트 경로와 실제 출력이 일치하는지 확인하고, 다른 터미널과 CI에서도 같은 명령을 실행한다. 한쪽에서만 결과가 다르면 Compose 파일보다 실행 위치, CLI 버전, 활성 profile, shell 환경을 먼저 비교한다. 설정 변경 뒤 컨테이너가 계속 예전 값으로 뜨면 기존 컨테이너와 볼륨이 남았는지도 확인한다. 재현 기록에는 docker compose version, pwd, 사용한 -f와 --env-file, 실행 명령, 종료 코드, 핵심 출력만 남긴다.

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

경고 없이 기본값이 들어간 경우에는 배포가 성공해도 잘못된 이미지나 포트로 시작할 수 있다. 그래서 오류 메시지가 없다는 사실만으로 치환이 정상이라고 판단하면 안 된다.

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

pwd와 -f·--env-file 인자를 기록하고, --environment에서 문제 변수를 찾은 다음 config --images와 전체 config에서 최종값을 대조한다. shell 변수를 비우거나 명시해 한 번 더 비교한다. 검증은 작은 재현부터 시작한다. 복사한 최소 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. 공식 문서와 예시 화면으로 확인하기

config가 보여 주는 범위를 공식 명령 문서에서 확인한다. 현재 프로젝트의 실행 디렉터리와 -f 인자를 먼저 기록한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

config는 병합과 변수 치환이 끝난 실제 Compose 모델을 출력한다.

이 결과에서 image, ports, environment의 최종값을 확인한다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

치환에 쓰인 입력값은 별도 화면에서 확인한다. 공유 전 비밀값은 제거한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

config --environment는 Compose 모델 interpolation에 사용된 환경을 출력한다.

컨테이너 내부 environment 전체를 보여 주는 명령과 혼동하지 않는다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

두 명령의 질문을 나란히 비교한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

입력 환경과 최종 모델의 차이다.

입력부터 결과 순서로 보면 덮어쓰기 지점을 좁힐 수 있다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

같은 위치에서 두 명령을 연달아 실행한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

TAG 출처와 최종 image 확인 예시다.

CI에서는 PWD와 env-file 인자도 함께 기록한다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

치환 오류 점검 순서를 고정한다. 이 자료는 같은 Compose 버전과 같은 프로젝트 경로에서 얻은 결과인지 먼저 확인한다.

환경변수 오류 체크리스트다.

출력에 credential이 포함되지 않았는지 마지막에 확인한다. 값이 예상과 다르면 명령 인자와 렌더링된 모델을 저장한 뒤 한 조건씩 다시 실행한다.

5. 주의사항과 리스크

config 출력에는 치환된 비밀값이 나타날 수 있다. 공개 로그로 남기지 말고 비밀번호는 Compose secrets 사용을 검토한다.

6. 결론

입력과 결과를 분리하면 치환 오류를 빨리 찾을 수 있다. --environment로 출처를, config로 실제 적용 모델을 확인한다. 변경 전후의 렌더링 결과와 런타임 로그를 함께 남기면 다음 장애에서도 같은 순서로 재현할 수 있다.

7. 참고 링크

1. https://docs.docker.com/reference/cli/docker/compose/config/
2. https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/