🚀 SWAG : 당신의 homelab을 혁신할 Reverse Proxy Docker!

Source: Dev.to

SWAG란 정확히 무엇인가요?

SWAG는 nginx 기반의 올인원 리버스 프록시로, Let’s Encrypt SSL 인증서를 자동으로 관리해 줍니다. 쉽게 말해, 여러분의 디지털 문지기로서:

• 🔒 SSL 인증서로 서비스를 자동 보호
• 🌐 서비스를 고유한 서브도메인에 노출
• 🛡️ 중앙 인증을 통해 애플리케이션 보호
• 📋 간단한 설정만으로 모든 것을 관리

왜 SWAG를 선택해야 할까요?

SWAG를 사용하기 전에는 일반 nginx와 certbot을 직접 다뤘는데… 정말 골치 아팠습니다! 인증서 갱신 실패, 수동 nginx 설정, 도메인 관리 등 여러 문제를 한 번에 해결해 주는 것이 SWAG였습니다:

• 자동 와일드카드 인증서
• 인기 서비스용 사전 설정 파일 제공
• Docker와의 네이티브 통합
• 인증 지원 (Authelia, OAuth 등)

목표 아키텍처

제공업체 설정 예시 (Free)

1. Freebox 관리 페이지에 로그인
2. Freebox 설정 → 포트 관리
3. 포트 포워딩 설정:

💡 보안 팁: 80/443 포트를 바로 열기보다 커스텀 포트(예: 8443)를 사용하고 포워딩하면 더 안전합니다.

DuckDNS 설정

1. DuckDNS에 회원가입
2. 도메인 생성: monhomelab.duckdns.org
3. 토큰을 기록 (Docker에서 사용)

대체 DNS 제공업체

Cloudflare 설정 예시:

environment:
  - URL=mondomaine.com
  - VALIDATION=dns
  - DNSPLUGIN=cloudflare
  - EMAIL=votre-email@example.com
  - CLOUDFLARETOKEN=votre-api-token-cloudflare

공인 IP 확인

# 공인 IP 확인
curl ifconfig.me

# DuckDNS가 올바르게 가리키는지 확인
nslookup monhomelab.duckdns.org

IP가 일치하면 OK! 🎯

연결 테스트

# 로컬 서버 간단히 실행
python3 -m http.server 8080

# 외부에서 도메인으로 테스트
curl http://monhomelab.duckdns.org:8080

정상 동작하면 SWAG를 설치할 준비가 된 것입니다!

Docker Compose로 설치

환경 변수 준비

version: "3.8"

networks:
  web-proxy:
    external: false

services:
  swag:
    image: lscr.io/linuxserver/swag:latest
    container_name: swag
    cap_add:
      - NET_ADMIN
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Paris
      - URL=monhomelab.duckdns.org      # DuckDNS 도메인
      - VALIDATION=duckdns              # DuckDNS 인증
      - DUCKDNSTOKEN=12345678-1234-1234-1234-123456789012  # DuckDNS 토큰
      - SUBDOMAINS=wildcard             # *.monhomelab.duckdns.org 허용
      - EMAIL=votre-email@example.com
      - ONLY_SUBDOMAINS=false           # 메인 도메인도 사용 가능하도록
    volumes:
      - ./swag/data:/config
    ports:
      - "80:80"     # HTTP (HTTPS로 리다이렉트)
      - "443:443"   # HTTPS (보안 서비스)
    networks:
      - web-proxy
    restart: unless-stopped

주요 변수

• URL : 전체 도메인 (DuckDNS, Cloudflare 등)
• VALIDATION : DNS 제공업체에 맞는 인증 방식
• SUBDOMAINS=wildcard : 모든 서브도메인에 대한 인증서 생성
• DUCKDNSTOKEN : DNS 제공업체 토큰 / API 키
• ONLY_SUBDOMAINS=false : 메인 도메인도 동시에 사용 가능

SWAG 시작

docker-compose up -d swag
docker logs swag   # “Server ready”와 “Certificate renewal successful” 메시지가 보일 겁니다

생성된 폴더 구조

swag/data/
├── nginx/
│   ├── nginx.conf
│   ├── site-confs/
│   └── proxy-confs/     # ← 서비스별 프록시 설정
├── keys/
│   └── letsencrypt/     # ← SSL 인증서
└── log/

첫 번째 서비스 추가

서비스 1 : Home Assistant

같은 docker‑compose.yml에 아래 내용을 추가:

  homeassistant:
    image: homeassistant/home-assistant:stable
    container_name: homeassistant
    environment:
      - TZ=Europe/Paris
    volumes:
      - ./homeassistant/data:/config
    networks:
      - web-proxy
    ports:
      - "8123:8123"   # 로컬 직접 접근용 (선택)
    restart: unless-stopped

SWAG 프록시 설정

swag/data/nginx/proxy-confs/homeassistant.subdomain.conf 파일을 만들고:

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name homeassistant.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app homeassistant;
        set $upstream_port 8123;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }

    # WebSocket 지원 (Home Assistant 필수!)
    location /api/websocket {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app homeassistant;
        set $upstream_port 8123;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

설정 테스트

# 컨테이너가 실행 중인지 확인
docker ps | grep homeassistant

# 외부에서 접근 테스트
curl -k https://homeassistant.monhomelab.duckdns.org

Home Assistant 로그인 화면이 보이면 성공!

네트워크 트러블슈팅

전용 Docker 네트워크

SWAG, Home Assistant 등 모든 서비스가 동일한 Docker 네트워크(web-proxy)에 연결돼 있는지 확인하세요. 이렇게 하면 포트 공개 없이 컨테이너 이름(homeassistant, swag 등)만으로 서로 통신할 수 있습니다.

로그 관리

docker logs swag          # 리버스 프록시 로그
docker logs homeassistant

SWAG 로그는 swag/data/log/에도 저장됩니다.

설정 검증

• 인증서가 생성됐는지 확인:
  ls swag/data/keys/letsencrypt/live/monhomelab.duckdns.org/
• HTTP → HTTPS 리다이렉트 테스트:
  curl -I http://monhomelab.duckdns.org

와일드카드 인증서

SWAG는 자동으로 *.monhomelab.duckdns.org 와일드카드 인증서를 발급합니다. 서브도메인마다 별도 인증서를 만들 필요가 없습니다.

Authelia로 보안 강화 (보너스)

Authelia를 인증 미들웨어로 추가할 수 있습니다:

  authelia:
    image: authelia/authelia
    container_name: authelia
    environment:
      - TZ=Europe/Paris
    volumes:
      - ./authelia/config:/config
    networks:
      - web-proxy
    restart: unless-stopped

그 후 서비스 프록시 파일에 다음을 삽입:

    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        auth_request /authelia;
        auth_request_set $user $upstream_http_remote_user;
        proxy_set_header Remote-User $user;
        # …
    }

전체 설정 방법은 Authelia 공식 문서를 참고하세요.

최종 결과

• 단일 진입점(https://monhomelab.duckdns.org)이 모든 서비스로 라우팅
• 자동 갱신되는 SSL 인증서
• 중앙화된 로그와 Docker 네트워크 관리

흔히 발생하는 문제와 해결법

결론

SWAG는 homelab에 SSL이 적용된 리버스 프록시를 손쉽게 구축하도록 도와줍니다. Docker, DuckDNS(또는 다른 DNS 제공업체)와 사전 설정된 구성 파일을 결합하면 시간·보안·유연성을 크게 향상시킬 수 있습니다.

다음 단계

• SWAG 공식 문서
• 지원 DNS 제공업체 전체 가이드
• Authelia 튜토리얼
• 전체 스택 예시 (Traefik, Portainer 등)