설치 및 시작하기

Docker를 사용하여 Nginx Proxy Guard를 쉽고 빠르게 설치하는 방법

필요 조건 (Prerequisites)

Docker 24.0+ 및 Docker Compose 2.20+
최소 1GB RAM, 10GB 디스크 공간
(선택) SSL 인증서용 도메인 이름
(선택) GeoIP용 MaxMind 라이선스 키

빠른 설치 (Quick Start)

# 설치 디렉토리 생성
mkdir -p ~/nginx-proxy-guard && cd ~/nginx-proxy-guard

# 필수 파일 다운로드
wget https://raw.githubusercontent.com/svrforum/nginxproxyguard/main/docker-compose.yml
wget -O .env https://raw.githubusercontent.com/svrforum/nginxproxyguard/main/env.example

# 보안 시크릿 생성 (중요!)
sed -i "s/DB_PASSWORD=.*/DB_PASSWORD=$(openssl rand -base64 24)/" .env
sed -i "s/JWT_SECRET=.*/JWT_SECRET=$(openssl rand -hex 32)/" .env

# 서비스 시작 (볼륨 자동 생성)
docker compose up -d

UI 접속

관리 패널: https://localhost:81
프록시: http://localhost:80 / https://localhost:443

기본 자격 증명 (Default Credentials)

중요: 첫 로그인 후 반드시 기본 자격 증명을 변경하세요.

사용자명: admin
비밀번호: admin

환경 설정

.env 파일을 편집하여 시스템을 구성합니다.

필수 설정

# 보안 시크릿 (반드시 변경!)
DB_PASSWORD=<강력한_비밀번호>
JWT_SECRET=<32자_hex_문자열>

선택 설정

# MaxMind GeoIP (국가별 차단 기능 사용 시)
MAXMIND_LICENSE_KEY=<라이선스_키>
MAXMIND_ACCOUNT_ID=<계정_ID>

# Let's Encrypt (자동 SSL 인증서 발급 시)
ACME_EMAIL=admin@example.com
ACME_STAGING=false

# 타임존
TZ=Asia/Seoul

Docker 서비스

서비스	설명	포트
`nginx`	리버스 프록시 + WAF	80, 443 (TCP/UDP)
`ui`	관리 웹 인터페이스	81
`api`	Go 백엔드 API	8080 (내부)
`db`	PostgreSQL 17	5432 (내부)
`valkey`	Redis 호환 캐시	6379 (내부)

Docker 볼륨

볼륨	용도
`npg_postgres_data`	데이터베이스 저장
`npg_valkey_data`	캐시 데이터
`npg_nginx_data`	Nginx 설정, 인증서, 로그
`npg_api_data`	백업 및 API 데이터
`npg_ui_data`	UI SSL 인증서

포트 설정

기본 포트

포트	프로토콜	용도
80	TCP	HTTP
443	TCP	HTTPS (HTTP/2)
443	UDP	HTTPS (HTTP/3 QUIC)
81	TCP	관리 UI

포트 변경

docker-compose.yml에서 포트 매핑을 수정합니다:

services:
  nginx:
    ports:
      - "8080:80"        # HTTP 포트 변경
      - "8443:443/tcp"   # HTTPS 포트 변경
      - "8443:443/udp"   # HTTP/3 포트 변경
  ui:
    ports:
      - "3000:443"       # 관리 UI 포트 변경

업그레이드

# 설치 디렉토리로 이동
cd ~/nginx-proxy-guard

# 최신 docker-compose.yml 다운로드
wget -O docker-compose.yml https://raw.githubusercontent.com/svrforum/nginxproxyguard/main/docker-compose.yml

# 최신 이미지로 서비스 재시작
docker compose pull && docker compose up -d

백업 & 복원

백업

관리 UI에서 설정 > 백업 메뉴를 통해 백업을 생성하거나:

# 수동 백업 (컨테이너 내부)
docker exec npg-api /app/backup.sh

복원

# 백업 파일로 복원
docker exec npg-api /app/restore.sh /path/to/backup.tar.gz

초기 설정 체크리스트

기본 비밀번호 변경 - 첫 로그인 후 즉시
2FA 활성화 - 설정 > 계정에서 TOTP 설정
HTTPS 설정 - 관리 UI용 인증서 설정
GeoIP 설정 - MaxMind 라이선스 키 입력
DNS Provider 설정 - Let's Encrypt 자동 발급용
백업 스케줄 설정 - 정기 백업 자동화

문제 해결

컨테이너가 시작되지 않음

# 로그 확인
docker compose logs -f

# 특정 서비스 로그
docker logs npg-api
docker logs npg-proxy
docker logs npg-db

데이터베이스 연결 실패

# DB 컨테이너 상태 확인
docker ps | grep npg-db

# DB 연결 테스트
docker exec -it npg-db psql -U postgres -d nginx_proxy_guard -c "SELECT 1;"

Nginx 설정 오류

# Nginx 설정 문법 검사
docker exec npg-proxy nginx -t

# Nginx 재로드
docker exec npg-proxy nginx -s reload

권한 문제

# 볼륨 권한 확인
docker exec npg-proxy ls -la /etc/nginx/conf.d/
docker exec npg-api ls -la /app/data/