현대적인 애플리케이션 개발 환경에서 도커(Docker)와 도커 컴포즈(Docker Compose)는 없어서는 안 될 필수적인 도구로 자리 잡았습니다. 특히 마이크로서비스 아키텍처(MSA)가 보편화되고, 클라우드 네이티브 환경으로의 전환이 가속화되면서 컨테이너 오케스트레이션의 중요성은 날로 커지고 있습니다. 이러한 환경에서 가장 빈번하게 마주치는 문제 중 하나가 바로 '환경변수 관리'입니다. 개발 로컬 환경, 테스트 서버, 그리고 실제 운영(Production) 환경에 따라 데이터베이스 접속 정보, API 키, 디버그 모드 설정 등을 다르게 가져가야 하는데, 이때 가장 핵심적인 역할을 하는 것이 바로 .env 파일입니다.
하지만 도커 컴포즈를 사용하다 보면, 분명히 .env 파일에 값을 정의해 두었음에도 불구하고 컨테이너 내부에서 해당 변수를 인식하지 못하거나, 비어 있는 값(null)으로 처리되어 애플리케이션이 실행되지 않는 난감한 상황을 겪게 됩니다. "왜 내 설정은 무시되는 걸까?"라는 의문과 함께 수많은 구글링을 해보지만, 명확한 원인을 찾지 못해 시간을 허비하는 경우가 많습니다. 단순히 파일이 존재한다고 해서 도커가 자동으로 모든 것을 해결해주지는 않기 때문입니다.
이 글에서는 도커 컴포즈 환경에서 .env 파일이 인식되지 않는 다양한 원인을 심층적으로 분석하고, 상황별로 적용할 수 있는 구체적인 해결 가이드를 제시합니다. 파일의 위치 문제부터 문법적 오류, 우선순위 충돌, 그리고 캐싱 문제까지 개발자가 놓치기 쉬운 체크리스트를 꼼꼼하게 다룰 것입니다. 또한, 단순한 문제 해결을 넘어 보안과 운영 효율성을 고려한 환경변수 관리 베스트 프랙티스까지 함께 알아봄으로써, 더욱 견고한 데브옵스(DevOps) 환경을 구축하는 데 도움을 드리고자 합니다.
도커 컴포즈와 환경변수의 작동 원리 이해하기
문제를 해결하기 위해서는 먼저 도구의 작동 원리를 정확히 이해하는 것이 선행되어야 합니다. 도커 컴포즈는 기본적으로 프로젝트 루트 디렉토리에 있는 .env 파일을 자동으로 탐색하여 로드하도록 설계되어 있습니다. 하지만 이 과정에서 '변수 치환(Variable Substitution)'과 '컨테이너 환경변수 주입'이라는 두 가지 서로 다른 개념이 혼재되어 사용되기 때문에 혼란이 발생합니다. 이 섹션에서는 도커가 환경변수를 처리하는 근본적인 메커니즘을 살펴봅니다.
.env 파일의 역할과 변수 치환(Interpolation)
도커 컴포즈가 실행될 때 가장 먼저 수행하는 작업 중 하나는 docker-compose.yml 파일을 파싱하는 것입니다. 이때 .env 파일은 주로 '전처리' 단계에서 사용됩니다. 즉, YAML 파일 내부에 ${VARIABLE} 형태로 작성된 변수들을 .env 파일에 정의된 실제 값으로 바꿔치기하는 과정입니다. 이를 변수 치환 또는 인터폴레이션(Interpolation)이라고 합니다.
중요한 점은, .env 파일에 정의된 변수가 자동으로 컨테이너 내부의 환경변수(Environment Variable)로 설정되는 것은 아니라는 사실입니다. 많은 개발자가 범하는 실수가 바로 여기에 있습니다. .env 파일은 기본적으로 docker-compose.yml 파일을 완성하기 위한 '설정값 저장소' 역할을 하며, 이를 컨테이너 내부로 전달하기 위해서는 별도의 명시적인 설정이 필요합니다. 만약 이 과정을 생략한다면, 호스트 머신에서는 변수가 보이지만 정작 실행된 컨테이너 내부에서는 해당 값을 찾을 수 없게 됩니다.
기본 경로와 우선순위 규칙
도커 컴포즈는 기본적으로 docker-compose.yml 파일이 위치한 동일한 디렉토리에서 .env라는 이름의 파일을 찾습니다. 만약 파일명이 다르거나 다른 경로에 있다면 자동으로 인식하지 않습니다. 또한, 환경변수는 여러 경로를 통해 주입될 수 있는데, 도커는 명확한 우선순위 규칙을 가지고 있습니다. 이 순서를 모르면 의도치 않은 값이 적용되는 '유령 변수' 현상을 겪을 수 있습니다.
- 1순위: 도커 컴포즈 실행 시 CLI에서 직접 주입한 값 (예: environment 섹션 또는 쉘 환경변수)
- 2순위: 쉘(Shell)에 이미 export 되어 있는 환경변수
- 3순위: .env 파일에 정의된 값
- 4순위: Dockerfile 내의 ENV 지시어로 정의된 기본값
특히 호스트 운영체제의 쉘에 동일한 이름의 환경변수가 설정되어 있다면, .env 파일의 값보다 쉘의 값이 우선하여 적용된다는 점을 반드시 기억해야 합니다. 이는 로컬 개발 환경에서 이전에 설정해둔 값이 계속 적용되어 혼란을 주는 주된 원인입니다.
환경변수 인식 실패의 주요 원인과 점검 포인트
이론적인 배경을 이해했다면, 이제 실전에서 마주하는 구체적인 문제 상황들을 분석해볼 차례입니다. .env 파일이 무시되거나 잘못 읽히는 경우는 대부분 사소한 설정 실수나 문법적 오류에서 기인합니다. 아래의 점검 포인트들을 하나씩 따라가며 자신의 설정을 검토해 보시기 바랍니다.
1. 파일 위치 및 명명 규칙 위반
가장 흔하면서도 간과하기 쉬운 실수는 파일의 위치입니다. 프로젝트 구조가 복잡해지면서 docker-compose.yml 파일이 루트가 아닌 하위 폴더(예: deploy, infra 등)에 위치하는 경우가 있습니다. 이때 .env 파일이 프로젝트 루트에 그대로 남아있다면, 하위 폴더에서 실행되는 도커 컴포즈 명령은 상위 디렉토리의 .env 파일을 자동으로 찾지 못할 수 있습니다.
체크 포인트: 터미널에서 도커 컴포즈 명령어를 실행하는 '현재 작업 디렉토리(CWD)'에 .env 파일이 존재하는지
댓글
댓글 쓰기