도커 컨테이너에서 환경 변수 설정하는 최적의 방법 [실전 가이드]

요즘 도커를 활용한 컨테이너 기반 개발이 점점 일반화되고 있습니다. 저도 최근 프로젝트에서 다양한 환경(개발, 테스트, 운영)별로 설정을 분리해야 했는데요. 그 과정에서 환경 변수 관리가 생각보다 까다로운 문제였습니다. 이번 글에서는 도커 컨테이너에서 환경 변수를 설정하고 관리하는 실전적인 방법을 소개해드리려 합니다.

환경 변수, 왜 중요할까요?

본격적인 내용에 앞서, 환경 변수가 왜 중요한지 잠깐 이야기해볼게요. 환경 변수란 애플리케이션이 실행되는 환경에 저장된 동적 값으로, 코드와 설정을 분리하는 핵심 요소입니다.

우리가 일상에서 자주 접하는 다음과 같은 설정들이 대표적인 환경 변수입니다:

애플리케이션 포트(PORT)
데이터베이스 연결 정보(DB_HOST, DB_USER)
API 키와 비밀값(API_KEY, SECRET_KEY)
서비스 도메인 주소(SERVICE_URL)

이러한 값들을 코드에 직접 하드코딩하면 환경마다 코드를 변경해야 하는 번거로움이 생기고, 보안 취약점이 될 수도 있습니다. 그런데 막상 도커에서 환경 변수를 어떻게 설정하고 관리해야 하는지 고민이 되곤 합니다.

이제 도커에서 환경 변수를 다루는 두 가지 주요 방법을 자세히 살펴보겠습니다.

도커에서 환경 변수 설정하는 2가지 방법

1. Dockerfile 내에서 환경 변수 직접 정의하기

가장 기본적인 방법은 Dockerfile 내에서 ENV 지시어를 사용하여 환경 변수를 직접 정의하는 것입니다.

dockerfile

FROM node:14
WORKDIR /app
COPY package.json .
RUN npm install
COPY . .

# 환경 변수 정의
ENV PORT=80
ENV NODE_ENV=production

EXPOSE $PORT
CMD ["npm", "start"]

여기서 ENV PORT=80은 PORT라는 이름의 환경 변수에 80이라는 기본값을 지정한 것입니다. 그리고 EXPOSE $PORT에서 $를 사용해 해당 환경 변수 값을 참조하고 있습니다.

컨테이너 실행 시에는 다음과 같이 --env 또는 -e 옵션으로 값을 재정의할 수 있습니다:

bash

# 긴 형식 옵션 사용
docker run -d -p 3000:8000 --env PORT=8000 --name api-server api-node:latest

# 짧은 형식 옵션 사용
docker run -d -p 3000:8000 -e PORT=8000 -e NODE_ENV=development --name api-server api-node:latest

이렇게 실행하면 Dockerfile에서 정의한 기본값(PORT=80)이 아니라 실행 시 지정한 값(PORT=8000)이 컨테이너 내부에 설정됩니다.

2. 환경 변수 파일(.env) 사용하기

여러 환경 변수가 필요한 경우 매번 명령줄에 입력하는 것은 불편합니다. 이럴 때는 환경 변수 파일을 만들어 한 번에 설정할 수 있습니다.

먼저 프로젝트 루트 디렉토리에 .env 파일을 생성합니다:

# .env 파일 예시
PORT=8000
NODE_ENV=development
DB_HOST=localhost
DB_USER=admin
DB_PASS=secret
API_KEY=your_api_key_here

이제 이 파일을 컨테이너 실행 시 --env-file 옵션으로 전달합니다:

bash

docker run -d -p 3000:8000 --env-file ./.env --name api-server api-node:latest

이 방법의 장점은 여러 환경 변수를 파일로 관리할 수 있고, 환경별로 다른 파일(.env.dev, .env.prod 등)을 만들어 쉽게 전환할 수 있다는 점입니다.

환경 변수 설정 시 주의할 점

🟢 장점

코드와 설정을 분리하여 유연한 애플리케이션 구성이 가능합니다
동일한 이미지로 여러 환경(개발, 테스트, 운영)에서 다르게 실행할 수 있습니다
민감한 정보를 코드에서 분리하여 보안을 강화할 수 있습니다

🟡 취향

단순한 설정은 Dockerfile에 직접 정의해도 괜찮습니다
복잡한 설정이나 환경별 차이가 많은 경우 .env 파일이 더 편리합니다

🔴 주의사항

Dockerfile의 ENV로 정의한 값은 이미지에 포함되며, docker history <이미지> 명령으로 노출될 수 있습니다
.env 파일은 절대 Git 등의 소스 코드 저장소에 커밋하지 마세요
민감한 정보는 Docker Secrets이나 Kubernetes Secrets 같은 더 안전한 방법을 고려하세요

실제 Node.js 프로젝트에 적용해보기

제가 최근에 작업한 Node.js 프로젝트에서 어떻게 환경 변수를 활용했는지 공유해드리겠습니다.

프로젝트에서는 개발 환경과 운영 환경의 데이터베이스 설정이 달랐고, API 키도 환경별로 달랐습니다. 처음에는 Dockerfile에 직접 정의했지만, 민감한 정보가 이미지에 포함된다는 점이 우려되었죠.

결국 다음과 같은 방식으로 변경했습니다:

Dockerfile에는 필수적인 기본값만 정의:

dockerfile

FROM node:14
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .

# 꼭 필요한 기본 설정만 포함
ENV NODE_ENV=production
ENV PORT=80

EXPOSE $PORT
CMD ["node", "server.js"]

환경별로 다른 .env 파일 작성 (.gitignore에 추가):

# .env.development
PORT=3000
DB_HOST=localhost
DB_USER=dev_user
DB_PASS=dev_password
API_KEY=dev_api_key

# .env.production
PORT=80
DB_HOST=production-db.example.com
DB_USER=prod_user
DB_PASS=prod_secret_password
API_KEY=prod_api_key

컨테이너 실행 시 적절한 환경 파일 선택:

bash

# 개발 환경
docker run -d -p 3000:3000 --env-file ./.env.development --name app-dev app-node:latest

# 운영 환경
docker run -d -p 80:80 --env-file ./.env.production --name app-prod app-node:latest

이렇게 접근하니 코드는 전혀 변경하지 않고도 다양한 환경에서 유연하게 애플리케이션을 실행할 수 있었습니다.

마무리

도커 컨테이너에서 환경 변수를 효과적으로 관리하는 것은 확장 가능하고 유지보수하기 쉬운 애플리케이션을 구축하는 데 중요한 요소입니다.

처음에는 단순히 코드 내에 하드코딩하는 것이 편할 수 있지만, 프로젝트가 커지고 복잡해질수록 환경 변수의 중요성은 더욱 커집니다. 특히 CI/CD 파이프라인과 결합하면 환경 변수 관리의 효과는 더욱 극대화됩니다.

이 글이 도커에서 환경 변수를 관리하는 데 작은 도움이 되었기를 바라며, 컨테이너 기반 개발에 관심이 있는 분들에게 유용한 정보가 되었기를 바랍니다. 🙌

혹시 도커 환경 변수 설정에 관해 더 궁금한 점이 있으시면 댓글로 남겨주세요!