[Nginx] 환경변수 설정하고 사용하는 방법 docker- .env , Lua , 템플릿 렌더링(envsubst)

1. Nginx는 왜 환경변수 사용이 어려울까?

Nginx는 C로 작성된 고성능 웹 서버이기 때문에, 일반적인 쉘 환경 변수처럼 $ENV_VAR를 직접 인식하지 못합니다.

# ❌ 이렇게 쓰면 안됨
proxy_pass http://$BACKEND_URL;

Nginx는 $BACKEND_URL을 자체 변수로 해석하려 하기 때문에, 제대로 동작하지 않습니다.

---

2. Nginx에서 환경변수 사용하는 방법 4가지

📌 방법 1: env 지시어 (정적인 값 전달)

Nginx 메인 설정 (nginx.conf)의 main context에서 사용할 환경변수를 명시해줘야 합니다.

# nginx.conf (최상단에 선언)
env BACKEND_URL;

http {
    server {
        location / {
            proxy_pass http://$BACKEND_URL;
        }
    }
}

그리고 Nginx를 실행할 때는 해당 환경 변수를 포함해서 실행합니다:

export BACKEND_URL=localhost:8080
nginx -g 'daemon off;'

---

방법 2: Docker 환경에서 .env와 함께 사용

docker-compose.yml 에 환경변수를 정의하거나 .env 파일로 분리해서 사용합니다.

version: "3"
services:
  nginx:
    image: nginx:latest
    environment:
      - BACKEND_URL=host.docker.internal:8080
    volumes:
      - ./default.conf:/etc/nginx/conf.d/default.conf

그리고 nginx.conf 최상단에 다음처럼 추가합니다:

env BACKEND_URL;

예시 .env + docker-compose 연동

env_file:.env 파일을 참조
environment : Nginx 컨테이너 안으로 환경변수 전달
단, 여전히 proxy_pass http://$BACKEND_URL;는 직접 사용 불가! 아래 Lua 방식처럼 중간 처리가 필요함.

---

방법 3: Lua 스크립트로 처리 (가장 유연함)

기본 Nginx 설정으로는 $BACKEND_URL을 직접 사용할 수 없기 때문에 Lua 모듈을 써야 합니다.

Nginx에 ngx_http_lua_module이 설치되어 있다면, Lua로 환경변수 접근 가능!

# nginx.conf
env BACKEND_URL;

events {}

http {
    server {
        listen 80;

        location / {
        	//Lua 환경변수
            set_by_lua_block $backend_url {
                return os.getenv("BACKEND_URL")
            }

            proxy_pass http://$backend_url;
        }
    }
}

위의 set_by_lua_block으로 환경변수를 Nginx의 변수($backend_url) 로 변환해서 사용 가능

 

Lua 모듈을 쓸 수 있는 이미지로 바꾸기

기본 nginx 이미지에는 Lua가 없으므로 대신 OpenResty 이미지를 사용해야합니다.

# docker-compose.yml 수정
services:
  nginx:
    image: openresty/openresty:alpine
    ...

OpenResty는 Nginx + Lua 확장이 포함된 이미지입니다.

---

 

 

Lua를 사용하지 않고 환경변수를 .conf에 적용 하는 방법도 있습니다

방법 4: 템플릿 렌더링을 사용

컨테이너가 시작될 때 환경변수를 .conf에 주입하는 방식입니다.

예시: envsubst를 사용

 

먼저 nginx.conf.template 파일을 만들어줍니다.

nginx.conf.template

server {
    listen 80;
    location / {
        proxy_pass http://${BACKEND_URL};
    }
}

 

Dockerfile

FROM nginx:alpine
COPY nginx.conf.template /etc/nginx/templates/nginx.conf.template

 

docker-compose.yml 

services:
  nginx:
    image: custom-nginx
    ports:
      - "80:80"
    environment:
      - BACKEND_URL=host.docker.internal:8080
    command: /bin/sh -c "envsubst < /etc/nginx/templates/nginx.conf.template > /etc/nginx/nginx.conf && nginx -g 'daemon off;'"

이렇게 하면 컨테이너가 시작될 때 .env 변수로 nginx.conf를 생성합니다.

---

정리

 

방식	장점	단점
Docker .env	깔끔한 설정 분리	Nginx 내부에서는 가공 필요
Lua 방식	동적 처리 가능	Lua 모듈 필요( OpenResty 이미지 필요)
env 지시어	공식적으로 지원됨	proxy_pass엔 직접 사용 불가
템플릿 (envsubst)	공식 이미지 그대로 사용 가능	셸 스크립트 추가 필요

개발 초기거나 테스트용이면 envsubst 추천,
동적으로 많은 설정을 해야 하면 Lua + OpenResty 추천합니다.