Nginx Proxy Manager로 서버 프록시 라우팅부터 정적 페이지 라우팅까지 간단하게 구축하기

Nginx는 프론트부터 백엔드까지 프로젝트를 배포 및 운영하려면 꼭 고쳐야할 관문처럼 하나라고 생각한다. 하지만 처음 접하면 색깔도 없는 터미널에서 글자 하나만 틀려도 오류가 발생하고 원인을 찾는 것도 굉장히 어려워 골머리를 앓곤했다.

 

물론 쉬운 방법만이 능사는 아니지만, 기술적 역량이나 아키텍처에 공을 들여야하는 부분이 아니다보니 세세한 인프라 설정에 시간을 들이는 것 보다 어플리케이션 단에서 기술적 챌린지에 시간을 쏟는게 더 낫다고 본다.

 

---

Nginx Proxy Manager 란

https://nginxproxymanager.com/

Nginx Proxy Manager는 Nginx를 Web console기반으로 관리 가능한 GUI 오픈소스이다. 꽤 많은 유즈케이스를 커버 가능한데, 단순 서버 프록시 (라우팅)부터 정적 파일 호스팅까지 가능하다.

 

🚨 정적 파일 호스팅의 경우, repo issue에서 컨트리뷰터와 사용자들이 advanced기능을 이용해 커스텀 설정을 입력해 사용한 것이다. 따라서 nginx에 큰 변경이 있거나 Nginx Proxy Manager 새로운 버전에서 작동하지 않을 수 있으니, 기존에 구축된 시스템의 버전 업데이트를 유의하고 새로운 시스템을 구축하다가 동작하지 않으면 새로운 방법을 찾아야 한다.

 

---

Setup

Docker Compose 이용한 설치

공식 도큐먼트에서도 Docker Compose를 이용해 설치할도록 유도한다.

1. Docker Install documentation

2. Docker-Compose Install documentation

3. docker-compose.yml 작성

ersion: '3.8'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
      - /opt/websites:/mnt/user/appdata/NginxProxyManager/websites

• /opt/websites:/mnt/user/appdata/NginxProxyManager/websites : 정적 파일 호스팅을 위한 커스텀 설정이다. 
  • /opt/websites : 호스팅할 정적 파일이 들어있는 경로이다. 내가 원하는대로 설정하면 된다. (필자의 경우, 리액트 프로젝트가 빌드된 것이 바로 반영되도록 하기 위해, ..../Project-FE/dist/ 으로 설정하였다.
  • /mnt/user/appdata/NginxProxyManager/websites : Nginx Proxy Manager의 경로이다. 수정 불가. 오타없도록 유의

4. Run Docker Compose

docker-compose up -d

# If using docker-compose-plugin
docker compose up -d

 

 

 

---

Nginx Proxy Manager 사용

81번 포트가 관리 콘솔이다. 초기 계정은 admin@example.com / changeme 이다. 접속하면 바로 변경하게 된다.

 

 

기능

제공되는 주요 기능은 5가지 이다. 본 포스팅에서는 가장 대중적이고 직접 사용해본 1번 5번만 다룬다.

1. Proxy Hosts : 서버로 들어온 요청을 특정 위치로 라우팅한다

2. Redirection Hosts : 특정 도메인으로 접속된 요청을 다른 도메인으로 리다이렉션 시킨다.

3. Streams : Nginx의 새로운 기능인 Stream은 TCP/UDP 트래픽을 네트워크상의 다른 컴퓨터로 직접 전달해준다. 게임 서버나 FTP, SSH 서버 운영에 사용된다.

4. 404 Hosts : 404 응답 페이지 설정을 한다.

5. SSL Certificates : LetsEncrypt 기반 SSL 인증 설정을 관리한다.

 

 

5. SSL Certificates

필자는 이미 등록한 SSL이 있으니 무시하고 보면 된다..

 

letsencrypt를 기반으로 소유한 도메인에 대한 SSL 설정을 관리한다. Proxy Hosts에서 https SSL 접속을 지원하려면 가장 먼저 필수적으로 설정해야 한다. 도메인을 설정하는 방법은 2가지가 있는데, 사용할 도메인을 전부 정의하는 방법과 DNS Challenge 설정을 통해 와일드카드 설정을 하는 방법이다.

 

 

1. 사용할 도메인 명시적 정의하는 법

nginx로 들어온 요청을 라우팅하는 것이므로, 우선 사용할 도메인을 정의하고 서버 IP addr로 라우팅을 설정한다.

사진은 Route53이지만, CloudFlare 등 다른 DNS 환경도 마찬가지이다.

 

정의한 도메인을 모두 적고, 'Test Server Reachability'를 눌러 유효성을 검증한다. 검증이 완료하면 바로 'Save'로 생성하면 된다.

 

2. DNS Challenge, 와일드카드(에스터리스크) 사용하는 법

해당 도메인의 소유권을 확인시켜줌으로써, 도메인을 일일이 정의하지 않아도 된다. 다만, 더 자세한 인증정보를 요구하는데, Route53의 경우 IAM의 accessKey, secretKey를 요구하니, 각자의 판단을 따르면 될 것 같다.

 

 

1. Proxy Hosts

 

가장 많이 사용하는 기능으로 특정 도메인을 통한 접속을 서버 내 리소스로 라우팅할 수 있다. 두 가지 활용법이 있는데, 1. 포트를 기준으로 리소스로 라우팅과 2. 정적 파일 호스팅이다.

 

 

1-1. 포트 기준 리소스 라우팅

81번 포트로 접속하고 있는 nginx proxy manager 콘솔을 기준으로 알아보자. nginx.test.com 도메인을 서버를 향해 라우팅해 정의되었다면, 'Domain Names'에 정의된(사용할) 도메인을 적는다. SSL 인증서를 등록했다면 'Scheme'를 https로 변경하고, 'Forward Hostname / IP' 를 현재 서버 아아피로 작성하고 'Forward Port'는 Nginx proxy Manager web console이 LISTEN하고 있는 81번 포르를 적는다.

 

필요에 따라 SSL 탭에서 인증서를 설정하고 'Save'하여 프록시 설정을 생성하면 된다.

Nginx처럼 따로 service restart할 필요 없이, 짧은 대기시간 후 바로 적용된다.

 

 

1-2. 정적 파일 호스팅

필자의 경우 프론트 팀원들이 개발한 리액트 프로젝트를 개발 서버에 띄우려고 하는데, 2개의 모듈로 분리되어 있는 구조이다보니 기존에 쓰던 PM2 배포 방식을 사용하기 곤란했다. pnpm을 이용해 별도로 빌드하고, 빌드 폴더 안에 있는 각 모듈의 index.html만 라우팅하면 된다고 해서 구현해보았다.

 

NginxProxyManager/nginx-proxy-manager 레퍼의 이슈 타레(Use nginx-proxy-manager as web server #280)를 보고 구현했다.

 

docker-compose.yml을 작성할 때, /opt/websites 에 대한 설명을 기억하는가? 그 부분이 이 부분이다. NginxProxyManager 내부의 웹 호스팅 폴더와 /opt/websites를 마운트하게 된다. 본 nginx의 ../site_enbles/.., ../sites-available/..와 동일하다고 보면 될 것 같다.

 

필자의 경우, 테스트 서버 내의 리액트 프로젝트 구조가 아래와 같은데, 빌드시 dist 폴더 안에 모듈별로 생성되므로 /opt/websites/를 /home/sckwon/project/FE/dist로 변경하였다.

 

모듈에 연결할 도메인을 설정하고, 'Forward Hostname / IP'와 'Forward Port' 아무 값이나 적으면 된다. 파일에 라우팅할 것이지만, 필수 값으로 UI가 설정되어 있으므로 적어야 하기 때문이다. SSL도 마찬가지로 설정해준다.

 

🚨 Cache Assets을 사용한 경우, js와 css가 제대로 로드되지 않는 이슈가 있다는 코멘트가 있으니 테스트해보고 싶은 것이 아니라면 섣불리 사용하진 말자.

 

 

마지막으로 'Advanced' 탭에서 index.html라우팅을 설정하면 된다. 헷갈리면 안되는 부분이 Nginx proxy manager는 도커 컨테이너에 떠있으므로 서버 루트 경로를 기준으로 생각하면 안된다. docker compose에서 설정한대로, 마운팅햇떤 NginxProxyManager 내부 경로를 기준으로 적으면 된다.

 

필자의 경우 websites와 마운팅한 dist폴더 안에 모듈별로 빌드한 프로젝트가 생성되므로, root 경로에 해당 빌드 폴더의 이름을 적으면 된다. 그리고 'Save'를 눌러 생성하면 끝이다!

root /mnt/user/appdata/NginxProxyManager/websites/service-home;
index index.html;
location / {
    try_files $uri /index.html /index.html;
}

 

---

정적 파일 호스팅하느라 삽질한 저의 포스팅으로 다른 분들은 삽질하지 않길...

Nginx Proxy Manager로 평안한 배포 되길...

끝.