🐳 Docker 컨테이너 환경변수 관리, 친구한테 설명하듯 완전 정복하기

야, 너 혹시 이런 경험 있어?
로컬에서는 잘 돌던 앱을 컨테이너에 넣었더니 갑자기 "DB 연결 실패"가 뜨는 거. 아니면 더 무서운 거, 깃허브에 올린 이미지 안에 DB 비밀번호가 그대로 박혀 있던 거. 😱

이 두 사고의 공통점은 딱 하나야. 환경변수 관리를 대충 했다는 것. 오늘은 Docker에서 환경변수를 어디서, 어떻게, 어떤 순서로 넣고, 비밀값은 어떻게 숨기는지 커피 한 잔 하면서 차근차근 정리해볼게. 진짜 실무에서 바로 써먹을 수 있는 것만 골라왔어. ☕

🤔 1. 왜 굳이 환경변수로 설정을 넣어야 해?

이건 The Twelve-Factor App이라는 유명한 방법론에서 나온 원칙이야. 3번째 항목 "Config"에서 "설정은 코드와 분리해서 환경(environment)에 저장하라"고 말하거든.

Docker랑 이게 찰떡인 이유는 간단해. 도커 이미지는 한 번 빌드하면 불변(immutable)이야. 그런데 개발·스테이징·운영 환경마다 DB 주소, API 키, 로그 레벨이 다 다르잖아? 환경마다 이미지를 따로 빌드하면 "스테이징에서 테스트한 그 이미지"가 운영 이미지랑 달라지는 거야. 그럼 테스트한 의미가 없지.

🧰 2. 환경변수를 넣는 방법 총정리

Docker에서 환경변수를 넣는 길은 생각보다 많아. 하나씩 보자.

① Dockerfile의 ENV

FROM node:20-alpine
ENV NODE_ENV=production \
    PORT=3000
WORKDIR /app
COPY . .
CMD ["node", "server.js"]

ENV로 설정한 값은 이미지 안에 저장돼서, 이 이미지로 만든 모든 컨테이너에 기본값으로 들어가. 빌드 중간의 RUN 명령에서도 쓸 수 있고, 런타임에도 남아 있어.
그래서 비밀번호 같은 민감 정보를 ENV에 넣으면 절대 안 돼. docker history나 docker inspect로 누구나 볼 수 있거든.

② Dockerfile의 ARG (빌드 타임 전용)

ARG APP_VERSION=1.0.0
FROM node:20-alpine
ARG APP_VERSION
ENV APP_VERSION=${APP_VERSION}

docker build --build-arg APP_VERSION=2.1.0 -t myapp .

ARG는 빌드할 때만 존재하는 변수야. 컨테이너가 실행될 때는 사라져. 위 예제처럼 ENV로 옮겨 담아야 런타임에서도 쓸 수 있지.
여기서 자주 하는 착각이 하나 있어. "ARG는 빌드 후에 사라지니까 비밀값 넣어도 되겠지?" → 노노. 공식 문서에서도 ARG 값은 docker history로 노출될 수 있으니 비밀값에 쓰지 말라고 경고해. 그리고 FROM 앞에 선언한 ARG는 FROM 이후에서 쓰려면 위처럼 다시 ARG APP_VERSION으로 선언해야 해. 은근 헷갈리는 포인트!

③ docker run -e / --env-file

# 하나씩 넣기
docker run -e DB_HOST=db.local -e LOG_LEVEL=debug myapp

# 호스트에 이미 있는 변수 그대로 전달 (값 생략)
export API_TOKEN=abc123
docker run -e API_TOKEN myapp

# 파일로 한 번에
docker run --env-file ./prod.env myapp

-e VAR처럼 값을 생략하면 호스트 셸의 같은 이름 변수를 넘겨줘. 이 방식은 셸 히스토리에 값이 안 남는다는 소소한 장점도 있어.
--env-file 파일은 KEY=VALUE 한 줄씩 쓰고, #으로 시작하는 줄은 주석이야. 주의할 점은 따옴표가 문법적으로 벗겨지지 않고 값에 그대로 포함될 수 있다는 것. PASSWORD="abc"라고 쓰면 따옴표까지 값으로 들어가는 경우가 있으니, docker run용 env 파일에서는 따옴표 없이 쓰는 게 안전해.

④ Docker Compose의 environment / env_file

services:
  api:
    image: myapp:latest
    environment:
      NODE_ENV: production
      DB_HOST: db
    env_file:
      - ./common.env
      - ./api.env
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_pw
    secrets:
      - db_pw

secrets:
  db_pw:
    file: ./secrets/db_password.txt

실무에선 거의 이걸 쓰게 될 거야. env_file을 여러 개 나열하면 아래쪽 파일이 위쪽 값을 덮어써. 공통 설정 + 서비스별 설정으로 나누기 좋지.

⚠️ 3. 다들 한 번씩 당하는 함정: .env 파일의 정체

여기가 오늘의 꿀포인트야. Compose 쓸 때 프로젝트 폴더의 .env 파일과 env_file:로 지정한 파일은 역할이 완전히 달라.

그러니까 .env에 DB_PASSWORD=1234 써놓고 "왜 컨테이너에서 안 읽히지?" 하고 한 시간 날리는 거, 진짜 국룰이야. 😂 컨테이너에 넣고 싶으면 environment: DB_PASSWORD: ${DB_PASSWORD}처럼 명시적으로 연결하거나, env_file: .env로 지정해야 해.

# .env 내용이 제대로 치환됐는지 확인하는 최고의 방법
docker compose config

docker compose config는 변수 치환까지 끝난 최종 설정을 보여줘. 디버깅할 때 이거 하나면 반은 해결돼.
참고로 Compose의 변수 치환 문법도 쓸모가 많아. ${VAR:-default}는 값이 없거나 비어 있으면 기본값, ${VAR:?에러메시지}는 값이 없으면 실행 자체를 막아줘. 필수 변수에 :? 붙여두면 설정 누락 사고를 미리 막을 수 있지.

🥇 4. 누가 이기나? 환경변수 우선순위

같은 변수가 여러 곳에 설정돼 있으면 뭐가 이길까? Docker 공식 문서 기준 Compose에서 컨테이너 환경변수 우선순위는 이래 (위가 가장 강함).

즉 Dockerfile의 ENV는 "기본값", 실행할 때 넣는 값이 "최종 결정권자"야. 이 구조 덕분에 이미지 하나로 여러 환경을 커버할 수 있는 거지.
그리고 YAML 치환용 변수에서는 셸 환경변수가 .env 파일보다 우선해. CI에서 export TAG=v2 해두면 .env의 TAG보다 먼저 적용된다는 뜻!

🔐 5. 비밀값(Secret)은 환경변수에 넣어도 될까?

솔직히 말할게. 소규모 개발 환경에서 환경변수로 비밀번호를 넣는 건 흔하고, 당장 큰일 나진 않아. 하지만 운영 환경이라면 이야기가 달라. 환경변수에는 이런 약점이 있거든.

그래서 Docker는 시크릿(Secrets) 기능을 제공해. Compose에서 secrets를 쓰면 값이 컨테이너 안의 /run/secrets/<이름> 파일로 마운트돼. 환경변수 목록에는 나타나지 않지.

위 Compose 예제에서 POSTGRES_PASSWORD_FILE을 쓴 거 봤어? 공식 postgres, mysql 같은 이미지는 _FILE 접미사 규칙을 지원해서, 변수 값 대신 파일 경로를 주면 그 파일 내용을 읽어 비밀번호로 써. 내 앱에서도 같은 패턴을 쉽게 구현할 수 있어.

# Python 예시: _FILE 변수가 있으면 파일에서, 없으면 환경변수에서
import os

def get_secret(name):
    file_path = os.getenv(f"{name}_FILE")
    if file_path and os.path.exists(file_path):
        with open(file_path) as f:
            return f.read().strip()
    return os.getenv(name)

db_password = get_secret("DB_PASSWORD")

빌드 과정에서 비밀값이 필요할 때(예: 프라이빗 패키지 저장소 토큰)는 BuildKit의 secret mount를 써. 이건 이미지 레이어에 흔적이 안 남아.

# Dockerfile
# syntax=docker/dockerfile:1
FROM node:20-alpine
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci

# 빌드 명령
docker build --secret id=npm_token,src=./npm_token.txt -t myapp .

더 큰 규모라면 Kubernetes Secret, HashiCorp Vault, AWS Secrets Manager, Azure Key Vault 같은 전용 시크릿 저장소와 연동하는 게 정석이야. 다만 Kubernetes Secret은 기본적으로 base64 인코딩일 뿐 암호화가 아니라서, etcd 저장 시 암호화(Encryption at rest)와 RBAC 설정을 따로 챙겨야 해. 이거 모르는 사람 꽤 많아!

📊 6. 한눈에 보는 방법별 비교표

🛠️ 7. 실무에서 바로 쓰는 체크리스트

docker compose -f compose.yaml -f compose.prod.yaml up

🧪 8. 디버깅할 때 쓰는 명령어 모음

# 실행 중 컨테이너의 환경변수 확인
docker exec mycontainer env

# 설정된 환경변수 목록만 뽑기
docker inspect --format '{{json .Config.Env}}' mycontainer

# Compose 최종 설정(치환 완료) 확인
docker compose config

# 특정 서비스에 일회성으로 다른 값 주고 실행
docker compose run -e LOG_LEVEL=debug api

그리고 꼭 알아둘 것! 환경변수는 컨테이너가 생성될 때 정해져. 그래서 env 파일을 수정했다면 docker restart로는 반영이 안 되고, 컨테이너를 다시 만들어야 해. Compose라면 docker compose up -d가 설정 변경을 감지해서 컨테이너를 재생성해줘. "분명 바꿨는데 왜 그대로지?"의 범인은 대부분 이거야. 🕵️

🎯 마무리: 환경변수 관리는 결국 '습관'이다

정리해보면 이래.
• 이미지는 하나, 설정은 런타임에 주입
• ARG는 빌드용, ENV는 기본값용, 둘 다 비밀값 금지
• Compose의 .env는 YAML 치환용이라는 함정 기억하기
• 운영 비밀값은 secrets 파일 마운트나 전용 시크릿 저장소로
• .gitignore + .dockerignore 둘 다 챙기기

처음엔 귀찮아 보여도 한 번 구조를 잡아두면 배포가 진짜 편해져. 혹시 사내 인프라에 맞는 Docker·CI/CD 구성을 전문가에게 도움받고 싶다면, 재능넷에서 DevOps 경험이 풍부한 개발자를 찾아보는 것도 좋은 방법이야. 반대로 이런 노하우를 이미 갖췄다면 재능넷에서 네 기술을 나눠보는 것도 멋진 선택이고! 🙌

오늘 배운 거 하나만 기억해도 충분해.
"비밀번호는 이미지에 넣지 않는다."
이것만 지켜도 너는 이미 상위권 개발자야. 😎