🏠 Home Server Nginx Proxy Manager

홈서버의 모든 서비스를 하나의 도메인 체계로 통합 관리하는 자동화 도구

💡 프로젝트 배경

1. 클라우드의 제약에서 벗어나 홈서버로 가벼운 사이드 프로젝트를 배포하려 해도 클라우드 서비스(AWS, GCP 등)의 프리티어는 리소스 제약이 심했습니다. 반면, 집에서 놀고 있는 홈서버의 유휴 자원을 활용하면 비용 걱정 없이 넉넉한 환경에서 프로젝트를 호스팅할 수 있다는 점에 착안했습니다.

2. 포트폴리오와 데모의 유기적 연결 단순한 배포를 넘어, 메인 도메인(domain.com)은 개발자 포트폴리오로 활용하고 서브 도메인(todo.domain.com, chat.domain.com)에는 각 프로젝트의 데모 버전을 연결하고 싶었습니다. 이렇게 하면 하나의 도메인 아래에서 모든 작업물을 응집력 있게 보여줄 수 있기 때문입니다.

3. 반복적이고 지루한 설정의 자동화 하지만 서비스가 추가될 때마다 Nginx 리버스 프록시 설정을 작성하고, SSL 인증서를 발급받는 과정은 매우 번거롭고 실수가 잦은 작업이었습니다. 이 과정을 명령어 한 줄로 끝낼 수는 없을까?라는 고민에서 이 자동화 도구가 탄생했습니다.

4. 범용성과 확장성 특정 환경에 종속되지 않도록 도메인과 이메일 등 변경 가능한 정보는 환경 변수(.env)로 분리하여, 누구나 자신의 홈서버 환경에 맞춰 즉시 사용할 수 있도록 일반화했습니다.

🎯 이런 분들에게 추천합니다

페르소나	상황 및 사용법	결과
👨‍💻 포트폴리오 개발자	상황: 열심히 만든 사이드 프로젝트를 IP주소:3000 같은 투박한 주소로 보여주기 민망할 때. 사용: ./add_service.sh todo my-app:3000	https://todo.kangminjun.com 전문성 있는 서브도메인 URL로 서비스의 의미를 살림.
🏠 홈랩 운영자	상황: Plex, Home Assistant 등 **웹 대시보드(HTTP)**가 있는 내부 서비스의 포트 번호가 매번 헷갈릴 때. 사용: ./add_service.sh plex plex:32400	https://plex.home.net 복잡한 포트 번호 없이, 가족들도 쉽게 기억하고 접속 가능.
🛡️ 백엔드 엔지니어	상황: 로컬 개발 중 HTTPS 환경에서의 CORS, Secure Cookie 동작을 테스트해야 할 때. 사용: ./add_service.sh api my-server:8080	실제와 동일한 HTTPS 환경 복잡한 인증서 설치 과정 없이 명령어 한 줄로 실무와 동일한 환경 구축.

---

📖 프로젝트 소개

이 프로젝트는 Docker 기반의 홈서버 환경에서 **웹 서비스(HTTP/HTTPS)**를 위한 서브도메인 연결과 SSL 인증서 발급을 자동화합니다. 복잡한 Nginx 설정 파일을 직접 건드리지 않고, 스크립트 실행 한 번으로 안전한 HTTPS 서비스를 배포하세요.

✨ 주요 기능

• 🔒 자동 SSL 발급: Let's Encrypt 인증서 자동 발급 및 갱신
• 🛡️ 보안 강화: HSTS 헤더 기본 적용으로 A+ 등급 보안 설정
• 🚀 대용량 업로드 지원: client_max_body_size 1G 기본 설정으로 Nextcloud 등 파일 서버 운영 최적화
• ⚡ 정적 설정 파일: Nginx 성능 최적화를 위한 개별 .conf 파일 생성 방식

⚠️ 지원 범위 (Scope)

• 지원: 웹 서버, Web API, 웹 인터페이스가 있는 관리 도구 (Plex, Home Assistant 등)
• 미지원: HTTP가 아닌 TCP/UDP 서비스

---

🛠 아키텍처 및 작동 원리

이 프로젝트는 성능과 안정성을 위해 개별 정적 설정 파일 생성 방식을 사용합니다.

1. 트래픽 흐름

외부 사용자가 내 서버의 서비스에 접속하는 과정입니다.

graph LR
    User((사용자)) -- HTTPS --> Router[공유기]
    Router -- Port 443 --> Nginx(Nginx 프록시)
    
    subgraph Docker Network [도커 네트워크: service-discovery-network]
        Nginx -- Proxy Pass --> App1[웹 앱 1]
        Nginx -- Proxy Pass --> App2[웹 앱 2]
    end
    
    style Nginx fill:#f9f,stroke:#333,stroke-width:2px
    style Docker Network fill:#e1f5fe,stroke:#01579b,stroke-dasharray: 5 5

Loading

2. 서비스 추가

add_service.sh 스크립트가 수행하는 작업의 순서입니다.

sequenceDiagram
    participant Admin as 🧑‍💻 관리자
    participant Script as 📜 add_service.sh
    participant Certbot as 🔒 Certbot
    participant FS as 📂 파일시스템
    participant Nginx as 🚀 Nginx

    Admin->>Script: ./add_service.sh todo my-app:80
    
    Note over Script,Certbot: 1. SSL 인증서 발급
    Script->>Certbot: 인증서 발급 요청 (Let's Encrypt)
    Certbot-->>Script: 발급 성공 (pem 파일)
    
    Note over Script,FS: 2. 설정 생성
    Script->>FS: nginx/conf.d/todo.conf 생성
    
    Note over Script,Nginx: 3. 적용
    Script->>Nginx: 설정 테스트 (nginx -t)
    Script->>Nginx: 리로드 (nginx -s reload)
    
    Nginx-->>Admin: 🎉 서비스 배포 완료!

Loading

---

✅ 사전 준비

이 프로젝트를 시작하기 전에 다음 사항들이 반드시 준비되어 있어야 합니다.

1. 도메인
   • 본인 소유의 도메인 또는 DDNS 주소가 필요합니다. (예: joonamin.ddns.net)
   • 해당 도메인의 DNS(A 레코드)가 홈서버의 공인 IP를 가리키고 있어야 합니다.
2. 포트 포워딩
   • 공유기 설정에서 외부 포트 **80 (HTTP)**과 **443 (HTTPS)**을 Docker가 설치된 머신의 내부 IP로 포워딩해야 합니다.
   • 주의: 80번 포트가 막혀있으면 SSL 인증서 발급에 실패합니다.
3. Docker & Docker Compose
   • 서버에 Docker 엔진이 설치되어 있어야 합니다.

---

🚀 설치 및 실행

1. 프로젝트 클론 및 권한 설정

git clone https://github.com/joonamin/HomePort.git
cd HomePort

# [필수] 스크립트 실행 권한 부여
# 이 과정을 건너뛰면 Nginx 컨테이너가 정상적으로 실행되지 않습니다.
chmod +x add_service.sh nginx/init.sh

2. 환경 설정 (.env)

기본 제공되는 예제 파일을 복사하여 설정을 진행합니다.

cp .env.example .env
vim .env

.env 파일 내용 수정:

# 본인의 도메인 주소 (http:// 제외)
DOMAIN_BASE=joonamin.ddns.net

# SSL 인증서 만료 알림을 받을 이메일
EMAIL=joonamin44@gmail.com

# Docker 컨테이너 이름 (docker-compose.yml의 container_name과 일치해야 함)
CONTAINER_NAME=nginx-proxy

3. Nginx 프록시 서버 실행

docker-compose up -d

이제 Nginx와 Certbot 컨테이너가 실행됩니다.

---

✨ 서비스 추가하기

가장 중요한 단계입니다. 새로운 웹 서비스(예: todo-app)를 추가하는 방법을 설명합니다.

Step 1. 대상 서비스 실행

새로 띄울 서비스는 반드시 service-discovery-network 네트워크에 연결되어 있어야 Nginx가 접근할 수 있습니다.

예시: docker-compose.yml (새로운 서비스용)

version: '3'

services:
  my-web-app:
    image: nginx:alpine
    container_name: my-web-app  # 👈 이 이름을 바탕으로 nginx와 연결됩니다.
    expose:
      - "80"                    # 👈 add_service.sh에 사용될 포트명과 동일하게 맞춰주세요.
    networks:
      - service-discovery-network # 👈 필수!

networks:
  service-discovery-network:
    external: true              # 👈 [중요] 이 옵션이 없으면 nginx-proxy와 통신할 수 없습니다!
    name: service-discovery-network # 👈 명시적으로 이름을 지정하는 것이 안전합니다.

Step 2. 연결 스크립트 실행

nginx-proxy 디렉토리로 이동하여 스크립트를 실행합니다.

• 문법: ./add_service.sh [서브도메인] [컨테이너명:포트]

# 1. 서브도메인 연결 (예: todo.joonamin.ddns.net)
./add_service.sh todo my-web-app:80

# 2. 메인 도메인 연결 (예: joonamin.ddns.net)
# 서브도메인 자리에 '@'를 입력하세요.
./add_service.sh @ my-portfolio:3000

Step 3. 접속 확인

스크립트가 성공 메시지(🎉 Service Added)를 출력하면, 브라우저에서 https://todo.joonamin.ddns.net으로 접속해 봅니다.

---

❓ 트러블슈팅

자주 발생하는 문제와 해결 방법입니다.

1. 502 Bad Gateway 에러

Nginx까지는 도달했으나, Nginx가 뒷단의 서비스(컨테이너)를 찾지 못하는 경우입니다.

• 원인 1: 대상 컨테이너가 꺼져 있음.
• 원인 2: 대상 컨테이너가 service-discovery-network에 연결되지 않음. (docker network inspect service-discovery-network로 확인 가능)
• 원인 3: 스크립트 실행 시 포트 번호를 잘못 입력함.

2. SSL 인증서 발급 실패 (스크립트 에러)

• 원인 1: 공유기의 80번 포트가 포워딩되지 않음. (Certbot은 80번 포트로 인증을 수행합니다.)
• 원인 2: 도메인 DNS가 아직 전파되지 않음.
• 해결: 포트 포워딩을 확인하고, curl -I http://your-domain.com 명령어로 외부에서 접속이 되는지 확인하세요.

3. 서비스 삭제 방법

현재 자동 삭제 스크립트는 없습니다. 아래 명령어를 복사하여 수동으로 삭제하세요.

# 1. 설정 파일 삭제 (예: todo.joonamin.ddns.net.conf)
# 주의: 삭제하려는 도메인의 설정 파일명을 정확히 입력하세요.
rm nginx/conf.d/YOUR_DOMAIN.conf

# 2. Nginx 리로드 (설정 반영)
docker exec nginx-proxy nginx -s reload

echo "🗑️ Service deleted."

---

📂 디렉토리 구조 설명

.
├── add_service.sh       # 서비스 추가 및 SSL 발급 자동화 스크립트
├── docker-compose.yml   # Nginx 및 Certbot 컨테이너 정의
├── .env                 # 사용자 설정 (도메인, 이메일)
├── nginx/
│   ├── init.sh          # 컨테이너 시작 시 기본 설정 생성
│   └── conf.d/          # [중요] 생성된 서비스별 Nginx 설정 파일이 저장되는 곳
└── certbot/             # Let's Encrypt 인증서 저장소 (자동 관리됨)