빠른 흐름

# .env 파일 예시
# DB_HOST=db
# DB_PORT=5432
# APP_ENV=production

docker run --env-file .env -e PORT=4000 my-app

설정 흐름

어떤 환경 변수 전달 방식을 먼저 떠올리면 되나

--env-file로 환경변수를 파일에서 일괄 전달하는 이유

환경변수가 많아지면 -e KEY=value를 반복하면 명령이 길어지고 실수가 생긴다. --env-file은 .env 파일을 읽어 한 번에 주입한다. 파일은 이미지에 포함되지 않고 런타임에만 주입되므로 같은 이미지를 환경별로 다르게 실행할 수 있다.

# 개발 환경
docker run --env-file .env.development my-app

# 운영 환경
docker run --env-file .env.production my-app

Compose의 env_file vs environment 키 차이

env_file은 외부 파일에서 변수를 읽어 컨테이너에 주입한다. environment는 Compose 파일 안에 값을 직접 선언한다. 둘을 함께 쓰면 environment가 env_file 값을 덮어쓴다. 공통 설정은 파일로, 서비스별 오버라이드는 environment로 관리하는 패턴이 실용적이다.

services:
  app:
    image: my-app
    env_file:
      - .env           # 공통 설정 파일
    environment:
      PORT: "4000"     # 이 값이 .env의 PORT를 덮어씀
      APP_ENV: production

docker run의 --env-file과 Compose의 .env는 역할이 다르다

docker run --env-file은 컨테이너 안으로 실제 환경변수를 주입합니다. 반면 Compose의 루트 .env 파일은 YAML 안 ${VAR} 치환에도 쓰이고, env_file은 다시 컨테이너 환경 주입에 쓰입니다. 둘을 같은 것으로 보면 값이 어디에 쓰이는지 헷갈리기 쉽습니다.

services:
  app:
    image: my-app:${TAG}
    env_file:
      - app.env

여기서 루트 .env의 TAG는 Compose 파일 치환에 쓰이고, app.env는 컨테이너 내부 환경변수로 들어갑니다.

환경변수가 이미지가 아닌 런타임에 주입되어야 하는 이유

ENV 지시어로 Dockerfile에 값을 박으면 이미지 레이어에 고정된다. 이미지를 다시 빌드하지 않으면 변경이 불가능하고, 이미지를 공유하면 민감한 값도 함께 노출된다. 런타임 주입 방식은 이미지를 중립적으로 유지하면서 배포 환경에 맞는 설정을 분리한다.

# 나쁜 예: DB 주소가 이미지에 고정됨
ENV DB_HOST=prod-db.internal

# 좋은 예: 이미지는 중립, 실행 시 주입
# (Dockerfile에 ENV 없음 → docker run --env-file .env로 주입)

시크릿을 환경변수로 넘길 때의 노출 위험

환경변수는 편리하지만 완전히 격리된 공간이 아니다. 같은 호스트의 루트 권한 사용자는 /proc/PID/environ으로 컨테이너의 환경변수를 읽을 수 있다. docker inspect로도 값이 노출된다. 패스워드나 API 키 같은 시크릿은 Docker Secrets나 외부 Vault를 사용하는 것이 더 안전하다.

# 실행 중인 컨테이너의 환경변수가 inspect에 노출됨
docker inspect my-app | grep -A 20 '"Env"'

# 호스트에서 컨테이너 PID를 알면 /proc로도 접근 가능
# cat /proc/<PID>/environ

체크포인트

주의할 점

docker run --env-file .env my-app

.env 파일 안에 따옴표나 export 문법을 셸 스크립트처럼 섞어 두면 기대한 값과 다르게 들어갈 수 있습니다. Docker용 env 파일은 단순한 KEY=value 형식으로 유지하는 편이 안전합니다.