[Docker] 도커 컨테이너 환경변수 설정 : ENV & ARG

개요

도커 컨테이너를 구성할 때 유연성을 제공하는 두 가지 핵심 기능인 build-time 인수와 runtime 환경변수를 지원합니다.

 

이번 글에서는 빌드타임 인수(ARG)와 런타임 환경변수(ENV)에 대해 자세히 알아보겠습니다.

 

빌드타임 인수(ARG)

ARG는 Dockerfile에서 ARG 명령어를 사용하여 선언하며, 도커 이미지를 빌드하는 동안에만 사용할 수 있는 변수입니다. 컨테이너가 실행될 때는 ARG 값에 접근할 수 없습니다.

• 빌드 시점에만 사용되며, 컨테이너 실행 시에는 사용되지 않습니다.
• 기본값을 설정하거나, docker build 명령에서 --build-arg 옵션을 통해 값을 동적으로 설정할 수 있습니다.
• 이미지 히스토리에 값이 저장되므로 민감한 정보는 피해야 합니다.

---

빌드 시점 환경변수 사용하기

FROM node:18-alpine

# 빌드 시점에 사용할 변수 선언
ARG DEFAULT_PORT=80

# ENV로 빌드 변수 전달
ENV PORT $DEFAULT_PORT

WORKDIR /app
COPY package.json .
RUN npm install
COPY . .

# EXPOSE에 환경변수 사용
EXPOSE $PORT

CMD ["npm", "start"]

 

빌드 시 다른 포트를 지정하려면 다음과 같이 설정할 수 있습니다.

docker build -t my-app . --build-arg DEFAULT_PORT=8080

• ARG DEFAULT_PORT=80
  • 빌드 시점에 사용할 기본 포트를 설정합니다.
• ENV PORT $DEFAULT_PORT
  • ARG 값을 ENV로 전달하여 런타임 환경변수로 변환합니다.

 

런타임 환경변수(ENV)

런타임 환경변수는 Dockerfile에서 ENV 명령어로 정의합니다.

 

ENV는 컨테이너 실행 중에도 사용할 수 있는 환경변수입니다. 애플리케이션이 이 값을 읽어 동적으로 동작할 수 있습니다.

• 컨테이너 내부에서 실행되는 모든 프로세스가 환경변수에 접근할 수 있습니다.
• 애플리케이션 코드에서 환경변수를 읽어 동적으로 동작하게 만들 수 있습니다.
• 실행 시점에 --env 또는 --env-file로 값 변경 가능
• 민감한 정보 저장에 적합 (런타임에만 주입되기 때문)

 

---

런타임 시점 환경변수 사용하기

애플리케이션 코드

const express = require('express');
const app = express();

// 환경변수에서 포트 값을 읽어 설정
const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

 

런타임에서 환경변수를 설정하려면 다음과 같이 컨테이너를 실행하면 됩니다.

docker run -p 8080:3000 --env PORT=8080 my-app

• --env 옵션으로 PORT 값을 8080으로 설정합니다.
• 컨테이너 내부에서 process.env.PORT를 통해 이 값을 읽을 수 있습니다.

ARG와 ENV의 연계

Dockerfile에서 ARG로 정의한 값을 ENV로 전달하면, 빌드 시점의 유연성과 런타임의 접근성을 모두 활용할 수 있습니다.

# 빌드 시점 변수
ARG DEFAULT_PORT=80

# 런타임 환경변수로 전달
ENV PORT $DEFAULT_PORT

 

위와 같이 Dockerfile에서 ARG를 설정하고, ENV 명령어를 사용하면 다음과 같은 이점이 있습니다.

 

• 빌드 시 --build-arg로 포트 변경 가능
• 컨테이너 실행 시 --env로 포트 변경 가능
• 애플리케이션에서 포트 값 접근 가능

 

EXPOSE와 환경변수

EXPOSE 명령어는 컨테이너가 사용하는 네트워크 포트를 지정합니다. 환경변수와 함께 사용하면 더 유연한 설정이 가능합니다.

---

Dockerfile

FROM node:18-alpine

# 환경변수 정의
ENV PORT 3000

WORKDIR /app
COPY . .

# EXPOSE에 환경변수 활용
EXPOSE $PORT

CMD ["npm", "start"]

 

실행 시 커스터마이징

 

컨테이너를 실행할 때 포트를 환경변수로 동적으로 설정할 수 있습니다.

docker run -p 5000:5000 --env PORT=5000 my-app

• --env로 PORT 값을 5000으로 설정하면, 컨테이너 내부와 외부 모두 5000번 포트를 사용합니다.

 

환경변수 파일 사용

여러 환경변수를 관리하기 위해 .env 파일을 사용할 수 있습니다.

# .env.development
PORT=3000
NODE_ENV=development
DB_HOST=localhost

# .env.production
PORT=80
NODE_ENV=production
DB_HOST=prod-db

 

실행 시 각 환경에 맞는 .env 파일을 사용할 수 있습니다.

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

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

 

이렇게 환경변수 파일을 사용하면 여러 환경변수를 한 번에 관리하고 환경별로 다른 설정을 쉽게 적용할 수 있습니다.

 

단, .env 파일은 민감한 정보를 포함할 수 있으므로 반드시 .gitignore에 추가하여 버전 관리에서 제외해야 합니다.

 

 

결론

빌드타임 인수(ARG)와 런타임 환경변수(ENV)는 도커 컨테이너를 더욱 유연하게 만드는 핵심 기능입니다.

 

ARG는 빌드 시점의 커스터마이징을, ENV는 런타임의 동적 설정을 담당하며, 두 기능을 연계하여 사용하면 더욱 강력한 컨테이너 환경을 구성할 수 있습니다.