Docker Compose 달러 기호가 사라질 때: 보간과 컨테이너 셸 구분

직접 생성한 개념 이미지입니다. 실제 서비스 화면이나 구축·성능 시험 결과가 아닙니다.

Compose의 변수 경고나 빈 문자열이 보이면 먼저 값을 바꾸는 주체가 Compose인지 컨테이너 안의 셸인지 구분하세요. Compose 단계에서 문자 그대로의 달러 기호를 넘기려면 $$를 사용할 수 있지만, 이후 셸이 그 문자를 다시 해석하는지는 별도 문제입니다.

원인: YAML을 읽는 단계와 명령 실행 단계를 혼동한다

Compose는 설정의 달러 변수 표현을 해석할 수 있습니다. 정의되지 않은 변수에 기본값도 없으면 경고 후 빈 문자열로 바뀔 수 있습니다. 애플리케이션이 실행되기도 전에 값이 달라지는 상황입니다. 컨테이너 환경변수에 같은 이름이 있다는 이유만으로 Compose가 그 값을 알 것이라고 가정하지 마세요.

관찰	확인 위치	다음 판단
변수 미정의 경고	Compose 입력	출처·기본값
달러 그대로 전달 필요	YAML 값	$$ 검토
컨테이너에서 치환 필요	실행 명령	셸 사용 여부
config 정상·결과 다름	앱 입력	실행 단계 점검

1. 비밀값 대신 시험용 문자열로 재현한다

운영 파일을 덮지 말고 승인된 별도 시험 디렉터리에서 아래처럼 비밀이 아닌 값으로 구성합니다. alpine 이미지의 다운로드와 실행에는 별도 네트워크·환경 조건이 필요합니다. 이 예시는 실제 실행 결과가 아닌 설명용입니다.

services:
  demo:
    image: alpine:3.22
    environment:
      DEMO_TEXT: hello
    command: ["sh", "-c", "echo $$DEMO_TEXT"]

이 예시는 Compose에서 달러를 남긴 후 sh가 컨테이너 환경변수를 해석하도록 의도한 구성입니다. 실행 프로그램이 셸이 아니라면 같은 결과를 기대할 수 없습니다. 입력 위치마다 무조건 달러를 두 배로 늘리는 처방은 피하세요.

2. 실행 전에 해석된 설정을 확인한다

docker compose version
docker compose -f compose.yaml config

실제로 사용할 작업 경로와 -f, --env-file 옵션을 동일하게 맞춰 확인합니다. config는 해석한 설정을 보여 주므로 값이 어느 단계에서 달라지는지 나눠 볼 수 있습니다. 출력에 비밀번호·토큰이 포함될 수 있어 운영 설정 전체를 공개 로그나 채팅에 복사하지 마세요.

Compose가 값을 알아야 하는 자리는 ${NAME}이나 기본값·필수값 표현을 검토하고, 컨테이너 안에서 해석하려는 자리는 해당 명령의 실행 방식을 확인합니다. 단일 인용부호를 YAML과 .env에서 똑같이 취급하지 마세요. .env의 단일 인용 값은 별도 문법 규칙을 따릅니다.

3. 확인과 복구를 구분한다

경고가 없어지는 것만으로 애플리케이션이 올바른 값을 사용한다고 단정하지 않습니다. 시험 환경에서 비밀이 아닌 결과를 확인하고, 운영 변경 전 기존 설정을 보존하세요. 실제 컨테이너의 명령·인수와 애플리케이션이 받는 값을 구분해야 합니다.

정상 설정이 확인된 뒤 필요한 서비스만 승인된 절차로 반영합니다. 설정 진단을 위해 운영 컨테이너를 무조건 재생성하거나 전체 서비스를 내리지 않습니다. 원하는 결과와 다르면 먼저 변경 전 설정으로 돌아갈 수 있어야 합니다.

FAQ

모든 달러 기호를 $$로 바꾸면 되나요? 아닙니다. Compose가 치환해야 하는 값도 있으므로 목적을 먼저 정합니다.

env_file에 변수가 있는데 왜 경고가 나나요? 컨테이너에 전달할 값과 Compose 설정 치환에 사용하는 값은 다를 수 있습니다.

config 출력은 공유해도 되나요? 비밀값을 포함할 수 있어 필요한 부분만 마스킹해 공유하세요.

공식 출처와 관련 글

자료 확인일: 2026년 10월 19일. 공식 문서 기반 설명이며 실제 서비스·명령 실행 시험은 수행하지 않았습니다. 설치 버전과 리전·지원 범위는 적용 전에 확인하세요.

Compose 보간 문법

변수 출처와 config 확인

관련 글: Compose .env와 env_file 역할 차이

적용 전 원본 설정을 보존하고 승인된 시험 범위에서 결과를 확인하세요.