🔄 서버 재부팅 시 NGINX가 먼저 실행되며 발생하는 upstream 에러 해결하기 (Docker + Blue/Green 배포 환경)

💡 배경

Docker를 활용해 프론트엔드 애플리케이션을 Blue/Green 방식으로 무중단 배포하고 있습니다.
eventor-front-blue-1, eventor-front-blue-2 와 같은 컨테이너들을 로드밸런싱하기 위해 NGINX의 upstream 설정을 활용하고 있습니다.

upstream frontend {
  server eventor-front-blue-1:8001;
  server eventor-front-blue-2:8002;
}

---

⚠️ 문제 상황

서버가 재부팅되면, NGINX 컨테이너가 먼저 실행되고, 그 뒤에 프론트엔드 애플리케이션 컨테이너들이 실행됩니다.
이때, NGINX가 먼저 올라오면서 upstream 설정에 명시된 컨테이너가 존재하지 않아 다음과 같은 에러가 발생합니다:

[emerg] host not found in upstream "eventor-front-blue-1:8001"

🚨 Docker 네트워크 내에서 정의된 컨테이너가 아직 생성되지 않았기 때문에 발생하는 문제입니다.

---

✅ 해결 전략

1. 기본 nginx.conf는 dummy upstream으로 설정하여 NGINX가 정상 기동되도록 설정
2. 프론트 애플리케이션이 기동된 후 실제 nginx.conf로 교체 및 nginx -s reload 수행

---

📁 nginx.base.conf (nginx-start.sh에서 복사할 기본 설정)

upstream frontend {
  server 127.0.0.1:65535;
}

65535 포트는 일반적으로 열려있지 않기 때문에, 실제 요청은 실패하지만 NGINX는 정상 기동됩니다.

---

🚀 nginx-start.sh (기본 conf 복사)

#!/bin/sh

DEFAULT_CONF="/nginx/nginx.base.conf"
TARGET_CONF="/nginx/nginx.conf"

cp "$DEFAULT_CONF" "$TARGET_CONF"

이 스크립트는 nginx 컨테이너가 실행될 때 /nginx/nginx.conf를 안전한 초기 상태로 세팅합니다.

---

📦 docker-compose.yml

services:
  nginx:
    container_name: nginx
    image: nginx:1.27.4
    restart: always
    command: ["/bin/sh", "/nginx-start.sh"]
    volumes:
      - ./nginx:/nginx
      - ./nginx-start.sh:/nginx-start.sh
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
      ...

---

🧾 default 설정: 502 커스텀 페이지 처리

location / {
    proxy_intercept_errors on;
    error_page 413 /errors/413.html;
    error_page 502 /errors/502.html;

    location = /errors/ {
        root /usr/share/nginx/html/;
        internal;
    }

    proxy_pass http://frontend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

✅ 프론트가 아직 기동되지 않았을 때 사용자에게는 커스텀 502 페이지를 보여줍니다.

---

🟢 이후 프론트 앱 실행 시 스크립트 (버전에 맞는 설정 적용)

#!/bin/bash

ACTIVE_VERSION=$(cat ./version.txt)

# nginx.conf 교체 및 리로드
cp nginx/nginx.$ACTIVE_VERSION.conf ../nginx/nginx.conf
cd .. && docker-compose exec nginx nginx -s reload

nginx.blue.conf, nginx.green.conf 등 실제 upstream 설정을 반영한 파일로 교체한 뒤 NGINX를 reload 합니다.

---

🔵 예: nginx.blue.conf

upstream frontend {
  server eventor-front-blue-1:8001;
  server eventor-front-blue-2:8002;
}

---

🎉 마무리

이렇게 설정하면 서버 재부팅 시 NGINX 기동 오류 없이 안전하게 시작되며,
프론트 애플리케이션이 올라온 이후에 적절한 설정으로 nginx를 reload함으로써 완전히 연결이 완료됩니다.

---

📌 참고 요약

항목	내용
문제	NGINX가 먼저 기동되며 upstream 컨테이너를 찾지 못해 에러
핵심 해결 전략	초기 dummy upstream 설정 → 앱 실행 후 실제 설정 적용 + reload
장점	서버 재부팅 시에도 NGINX 오류 없이 작동, 유연한 배포 가능