비밀번호와 설정값 주입하기: 환경 변수

코드에 하드코딩하면 안 되는 DB 비밀번호, API 키 등을 컨테이너가 실행될 때 환경 변수로 안전하게 주입하는 방법을 학습합니다.

우리가 만든 애플리케이션을 실행하려면 데이터베이스 비밀번호, 외부 API 키(예: OpenAI API Key), 포트 번호 등 다양한 설정값이 필요합니다. 이런 중요한 정보들을 소스 코드 안에 직접 적어두는 것(하드코딩)은 보안상 매우 위험합니다. 소스 코드가 깃허브(GitHub)에 올라가면 전 세계 누구나 비밀번호를 볼 수 있게 되기 때문입니다.

이를 해결하기 위해 개발자들은 환경 변수(Environment Variables)라는 것을 사용합니다. 도커 컨테이너 역시 실행되는 순간에 밖에서 이 환경 변수를 찔러 넣어줄 수 있는 기능을 제공합니다. 이번 에피소드에서는 컨테이너에 안전하게 설정값을 주입하는 방법을 배워보겠습니다.

왜 환경 변수를 사용해야 할까요?

환경 변수는 컴퓨터 운영체제 수준에서 제공하는 일종의 '메모장' 같은 것입니다. 프로그램은 실행되면서 이 메모장을 읽어 설정값을 파악합니다.

코드의 분리와 재사용성

환경 변수를 사용하면 코드를 단 한 줄도 수정하지 않고도, 프로그램을 완전히 다른 모드로 실행할 수 있습니다. 예를 들어, 동일한 서버 이미지를 하나는 개발 모드(Development)로, 다른 하나는 운영 모드(Production)로 띄우고 싶을 때, 오직 환경 변수 값만 바꿔주면 됩니다. 도커 이미지를 매번 새로 빌드할 필요가 없어지는 것이죠.

환경 변수로 관리해야 하는 정보들

데이터베이스 연결 주소(URL) 및 비밀번호
소셜 로그인(OAuth) 클라이언트 ID 및 시크릿
OpenAI, Stripe 등 결제 및 AI 서비스의 API 키
개발 모드(dev)와 운영 모드(prod)를 구분하는 설정값

`-e` 옵션을 이용한 직접 주입

도커 컨테이너를 실행할 때, 명령어에 `-e` (environment) 옵션을 사용하여 환경 변수를 주입할 수 있습니다.

`키=값` 형태의 주입

형식은 아주 간단합니다. `-e 환경변수명=값` 형태로 적어주면, 컨테이너 내부의 프로그램이 이 값을 인식하게 됩니다.

환경 변수 직접 주입하기

bash

docker run -e NODE_ENV=production -e PORT=8080 my-app

1docker run -e NODE_ENV=production -e PORT=8080 my-app
2-e 옵션을 사용해 NODE_ENV를 production으로 설정합니다.
3또 다른 -e 옵션으로 내부 포트 설정을 8080으로 지정합니다.
4이 상태로 my-app 컨테이너가 실행됩니다.

가장 대표적인 예시는 데이터베이스 컨테이너를 띄울 때입니다. 앞선 에피소드에서 살짝 보았던 PostgreSQL 실행 명령어를 떠올려 보세요.

docker run -d --name my-postgres -e POSTGRES_PASSWORD=mysecretpassword postgres:15

PostgreSQL 공식 도커 이미지는 보안을 위해 `POSTGRES_PASSWORD`라는 환경 변수가 없으면 아예 실행을 거부하도록 만들어져 있습니다. 이렇게 밖에서 암호를 주입해 주어야 정상적으로 컨테이너가 켜집니다.

`.env` 파일로 깔끔하게 관리하기

환경 변수가 한두 개일 때는 `-e` 옵션으로 충분하지만, 복잡한 웹 애플리케이션의 경우 환경 변수가 10개, 20개가 넘어가는 일도 흔합니다. 명령어 한 줄에 수십 개의 `-e` 옵션을 주렁주렁 다는 것은 매우 불편합니다.

이럴 때 사용하는 것이 바로 `.env` 파일입니다.

.env 파일과 --env-file 옵션 사용

프로젝트 폴더에 `.env`라는 텍스트 파일을 만들고, 필요한 변수들을 한 줄에 하나씩 적어둡니다.

# .env 파일 내용
DB_HOST=my-database
DB_USER=admin
DB_PASS=supersecret123
API_KEY=sk-xxxxxx

그리고 도커를 실행할 때 `--env-file` 옵션으로 이 파일을 지정해 주면 됩니다.

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

도커가 `.env` 파일을 읽어서, 파일 안의 모든 내용을 컨테이너 환경 변수로 알아서 주입해 줍니다. 코드가 훨씬 깔끔해지고 관리하기도 쉬워졌습니다!

.env 파일 보안 절대 규칙

1.env 파일은 절대 Git(버전 관리)에 커밋해서는 안 됩니다.
2반드시 .gitignore 파일에 .env를 추가하여 실수로 깃허브에 올라가는 것을 방지하세요.
3대신, 어떤 변수들이 필요한지 템플릿 역할을 하는 .env.example 파일은 버전을 관리하는 것이 좋습니다.

개념 퀴즈

퀴즈 답을 맞춰야 학습 완료가 됩니다.

수많은 환경 변수를 도커 명령어 하나에 다 적지 않고, 외부 텍스트 파일로 모아서 컨테이너에 한 번에 주입하려고 합니다. 이 때 사용하는 도커 옵션은 무엇인가요?

3줄 요약

1보안상 민감한 정보(비밀번호, API 키)는 소스 코드에 하드코딩하지 말고 환경 변수로 주입해야 합니다.
2도커는 컨테이너 실행 시 -e 옵션을 통해 개별 환경 변수를 전달할 수 있습니다.
3환경 변수가 많을 때는 .env 파일을 만들고 --env-file 옵션으로 깔끔하게 관리하는 것이 실무 표준입니다.