DuckDNS Traefik Setup

DuckDNS 무료 사용자를 위한 Traefik 설정 모음

DuckDNS 환경에서 Traefik을 쉽게 시작할 수 있도록 미리 구성해둔 설정 모음입니다. 한 번 실행해두면 다른 모든 프로젝트들이 자동으로 SSL과 도메인 라우팅을 받을 수 있습니다.

🎯 프로젝트 목적

대상 사용자

• DuckDNS 무료 서비스 사용자 (*.duckdns.org 도메인)
• 개인 개발자 및 홈랩 운영자
• Traefik 초보자부터 중급자까지

제공하는 가치

• ✅ 바로 사용할 수 있는 설정: Traefik 설정을 미리 구성해둔 템플릿
• ✅ DuckDNS 고려한 설정: 무료 DuckDNS 서비스 환경에 맞춘 구성
• ✅ 경로 기반 라우팅 예제: 서브도메인 제한 상황에서의 대안 제시
• ✅ SSL 설정 포함: Traefik의 Let's Encrypt 자동 발급 기능 활용
• ✅ 동작하는 예제: 실제 테스트해본 샘플 서비스 포함
• ✅ 상세한 설명: 설치와 사용법에 대한 가이드 제공

도움이 되는 상황

• 🔧 Traefik 처음 설정할 때
• 🌐 DuckDNS 무료 계정 서브도메인 제한이 있을 때
• 🔒 Traefik SSL 설정 방법을 찾을 때
• 📚 실제 동작하는 예제가 필요할 때
• 🛠️ Docker 네트워크 연결 방법을 알고 싶을 때

⭐ 포함된 내용

• 🚀 간단한 설치: .env 파일 설정 후 docker-compose로 실행
• 🔄 환경 변수 활용: 개인 정보는 .env 파일에서 관리
• 🌟 테스트 예제: routing-test 폴더에 웹/API 서비스 샘플
• 📖 사용법 가이드: 설치부터 사용까지 단계별 안내
• 🔧 문제 해결: 자주 발생하는 문제들과 해결 방법
• 💡 Traefik 학습: 라벨 시스템 사용법 상세 설명

🚀 빠른 시작

1. 환경 설정

# .env 파일 생성
cp .env.example .env

# 필수 설정값 수정 (.env 파일 편집)
# - DOMAIN: 본인의 도메인으로 변경 (예: your-domain.duckdns.org)
# - EMAIL: Let's Encrypt에 사용할 이메일
# - DASHBOARD_USER: 대시보드 인증 정보 (필요시)

주요 환경변수:

• DOMAIN: 사용할 도메인 (DuckDNS 등)
• EMAIL: SSL 인증서 발급용 이메일
• DASHBOARD_USER: 대시보드 기본 인증 (htpasswd 형식)
• DASHBOARD_PATH_PREFIX: 대시보드 경로 (기본: /traefik)
• CERT_RESOLVER: SSL 인증서 리졸버 (기본: letsencrypt)
• LOG_LEVEL: 로그 레벨 (DEBUG, INFO, WARN, ERROR)

2. 네트워크 생성

# 외부 네트워크 생성 (다른 프로젝트들이 연결할 네트워크)
docker network create traefik-network

3. 게이트웨이 실행

# 백그라운드에서 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f

4. 확인

• 대시보드: https://your-domain.duckdns.org/traefik/dashboard/#
• 자동 리다이렉트: https://your-domain.duckdns.org/traefik → https://your-domain.duckdns.org/traefik/dashboard/#
• 기본 인증: admin / admin123 (필요시)

주의사항: /traefik (슬래시 없음) 사용을 권장합니다. /traefik/ (슬래시 포함)은 브라우저에서 리다이렉트 오류가 발생할 수 있습니다.

5. 라우팅 테스트 (선택사항)

# 테스트 서비스 실행
cd routing-test
docker-compose up -d

# 테스트 확인
# 웹: https://your-domain.duckdns.org/test/
# API: https://your-domain.duckdns.org/testapi/health

📁 프로젝트 구조

duckdns-traefik-setup/
├── config/
│   └── traefik.yml          # Traefik 설정 파일
├── data/                    # Let's Encrypt 인증서 저장소
├── certs/                   # 추가 인증서 저장소
├── routing-test/            # 라우팅 테스트 예제
│   ├── docker-compose.yml   # 테스트 서비스 구성
│   ├── html/               # 웹 서비스 파일
│   ├── api/                # API 서비스 파일
│   └── README.md           # 테스트 가이드
├── docker-compose.yml       # Docker Compose 설정
├── .env                     # 환경 변수 설정
├── .env.example            # 환경 변수 예시
└── README.md

⚙️ Traefik 기능 활용

• ✅ SSL 인증서: Traefik의 Let's Encrypt 자동 발급/갱신 기능 사용
• ✅ HTTP → HTTPS 리다이렉트: Traefik의 리다이렉트 미들웨어 활용
• ✅ 대시보드 자동 리다이렉트: /traefik → /traefik/dashboard/# 자동 리다이렉트
• ✅ 대시보드: Traefik 내장 웹 관리 인터페이스 제공
• ✅ 외부 네트워크: 다른 Docker 프로젝트와 연결 가능
• ✅ 서비스 발견: Traefik의 Docker 라벨 기반 자동 라우팅

🔧 환경 변수

변수명	기본값	설명
DOMAIN	your-domain.duckdns.org	기본 도메인
EMAIL	your-email@example.com	Let's Encrypt 이메일
DASHBOARD_USER	admin:hash	대시보드 인증 정보
TRAEFIK_NETWORK	traefik-network	외부 네트워크 이름
HTTP_PORT	80	HTTP 포트
HTTPS_PORT	443	HTTPS 포트
DASHBOARD_PORT	8080	대시보드 포트
LOG_LEVEL	INFO	로그 레벨

대시보드 비밀번호 변경

새로운 비밀번호 해시 생성:

# htpasswd 설치 (Windows)
# choco install apache-httpd

# 또는 온라인 도구 사용
# https://hostingcanada.org/htpasswd-generator/

# 비밀번호 해시 생성
htpasswd -nbB admin your-new-password

생성된 해시를 .env 파일의 DASHBOARD_USER에 설정하세요.

🔄 관리 명령어

시작/중지

# 시작
docker-compose up -d

# 중지
docker-compose down

# 재시작
docker-compose restart

로그 확인

# 실시간 로그
docker-compose logs -f

# 특정 줄 수만 확인
docker-compose logs --tail=50

인증서 확인

# acme.json 파일 확인
ls -la data/acme.json

# 인증서 정보 확인
docker-compose exec traefik cat /letsencrypt/acme.json | jq .

🛠️ 트러블슈팅

일반적인 문제

1. 포트 충돌

   # 80, 443 포트 사용 중인 프로세스 확인
   netstat -ano | findstr :80
   netstat -ano | findstr :443
   

2. SSL 인증서 발급 실패

   • 도메인이 서버 IP를 올바르게 가리키는지 확인
   • 80 포트가 외부에서 접근 가능한지 확인
   • 방화벽 설정 확인

3. 대시보드 접근 불가

   • DNS 설정 확인: traefik.your-domain.com
   • 인증 정보 확인

4. 브라우저 개발자 도구 404 에러 (정상 현상)

   Failed to load resource: _hacks.de068122.js (404)
   Failed to load resource: _init.a396cff6.js (404)
   [Quasar] boot error: Failed to fetch dynamically imported module
   

   이는 정상적인 현상입니다:

   • Traefik v3.0.4 빌드에서 해당 JavaScript 모듈이 포함되지 않음
   • Quasar 프레임워크의 선택적(optional) 모듈 로드 시도
   • 대시보드 기능에는 전혀 영향 없음 - 모든 핵심 기능 정상 작동
   • SSL, 라우팅, API 통신 모두 완벽히 동작

   ⚠️ 주의: 이 404 에러를 해결하려고 추가 라우터나 설정을 변경하지 마세요. 불필요한 복잡성만 증가시키며 실제 문제 해결과는 무관합니다.

디버깅

로그 레벨을 DEBUG로 변경:

# .env 파일에서
LOG_LEVEL=DEBUG

# 재시작
docker-compose restart

불필요한 시도 내역 (참고용)

404 에러 해결을 위한 시도했지만 불필요했던 방법들:

1. Assets 전용 라우터 추가

   # ❌ 불필요한 시도
   - "traefik.http.routers.traefik-assets.rule=Host(`domain`) && PathPrefix(`/traefik/dashboard/assets`)"
   - "traefik.http.routers.traefik-assets.middlewares=traefik-assets-stripprefix"
   

   • 결과: 동일한 404 에러 지속
   • 이유: 파일이 Traefik 빌드에 존재하지 않음

2. 다양한 StripPrefix 설정 시도

   # ❌ 불필요한 시도들
   traefik-assets-stripprefix.stripprefix.prefixes=/traefik
   traefik-assets-stripprefix.stripprefix.prefixes=/traefik/dashboard
   

   • 결과: 라우팅은 정상이나 여전히 404 에러
   • 이유: 존재하지 않는 파일에 대한 라우팅 개선은 무의미

3. 서비스 변경 시도

   • api@internal vs dashboard@internal 비교
   • 결과: 서비스 변경과 무관하게 동일한 현상
   • 이유: 파일 부재가 근본 원인

📝 교훈: 브라우저 개발자 도구의 404 에러가 반드시 설정 문제를 의미하지 않습니다. 실제 기능 동작을 우선 확인하고, Traefik 자체의 빌드 특성을 고려해야 합니다.

📋 체크리스트

게이트웨이 설치 전:

• 도메인 DNS 설정 완료
• 80, 443 포트 방화벽 오픈
• Docker 및 Docker Compose 설치
• .env 파일 설정 완료

게이트웨이 실행 후:

• traefik-network 네트워크 생성
• 컨테이너 정상 실행 확인
• 대시보드 접근 가능
• SSL 인증서 자동 발급 확인

📚 사용 예제

다른 서비스에서 Traefik 사용하기

다른 Docker Compose 프로젝트에서 Traefik Gateway를 사용하는 방법:

version: '3.8'

services:
  my-app:
    image: nginx:alpine
    networks:
      - traefik-network
    labels:
      # Traefik 활성화
      - "traefik.enable=true"
      # 도메인 라우팅 (서브도메인)
      - "traefik.http.routers.my-app.rule=Host(`myapp.your-domain.duckdns.org`)"
      # 또는 경로 기반 라우팅
      - "traefik.http.routers.my-app.rule=Host(`your-domain.duckdns.org`) && PathPrefix(`/myapp`)"
      # HTTPS 적용
      - "traefik.http.routers.my-app.entrypoints=websecure"
      - "traefik.http.routers.my-app.tls=true"
      - "traefik.http.routers.my-app.tls.certresolver=letsencrypt"
      # 컨테이너 포트 (80이 아닌 경우)
      - "traefik.http.services.my-app.loadbalancer.server.port=3000"

networks:
  traefik-network:
    external: true

실제 동작 예제

routing-test 폴더에 실제 동작하는 완전한 예제가 포함되어 있습니다:

• 웹 서비스: Nginx 기반 정적 사이트 (/test/)
• API 서비스: Node.js 기반 REST API (/testapi/)
• SSL 자동 적용: Let's Encrypt 인증서 자동 발급
• 경로 기반 라우팅: 하나의 도메인에서 여러 서비스 운영

자세한 사용법은 routing-test/README.md를 참조하세요.