Homepage 대시보드에 Traefik 추가하기

Table of Contents

Homepage 대시보드의 강력한 기능 중 하나는 Docker와 연동하여 컨테이너의 상태를 표시하고, 각 서비스의 API와 통신하여 동적인 정보를 위젯으로 보여주는 것입니다.

이 가이드에서는 핵심 인프라 서비스인 Traefik 리버스 프록시를 Homepage 대시보드에 추가하는 방법을 단계별로 안내합니다. 컨테이너의 실행 상태뿐만 아니라, Traefik이 관리하는 라우터와 서비스의 개수 같은 통계 정보를 위젯으로 표시하는 방법을 다룹니다.

Docker 연동 설정 (`docker.yaml`)
#

먼저, Homepage가 Traefik 컨테이너의 상태를 확인할 수 있도록 Docker 엔진과 통신할 수 있게 설정해야 합니다. config/docker.yaml 파일을 열고 자신의 환경에 맞는 설정을 추가합니다.

Homepage와 Traefik이 동일한 서버에 있는 경우
#

가장 일반적인 경우로, Docker 소켓을 직접 연결합니다.

# config/docker.yaml

# 'my-docker'라는 이름으로 로컬 Docker 소켓을 연결합니다.
my-docker:
  socket: /var/run/docker.sock

Homepage와 Traefik이 다른 서버에 있는 경우
#

원격 서버의 Docker 데몬에 TCP로 접속합니다. 이 경우, 보안을 위해 반드시 TLS 인증을 사용해야 합니다.

# config/docker.yaml

# 'my-remote-docker'라는 이름으로 원격 Docker 호스트에 연결합니다.
my-remote-docker:
  host: 192.168.0.101 # Traefik이 실행 중인 서버의 IP 주소
  port: 2376          # TLS 보안 포트
  tls:
    keyFile: /app/config/tls/key.pem   # 컨테이너 내부 경로 기준
    caFile: /app/config/tls/ca.pem
    certFile: /app/config/tls/cert.pem

원격 Docker 데몬에 TLS를 설정하는 방법은 아래 가이드를 참고하십시오.

Docker 외부 연결을 위한 TCP 포트 2375 활성화 방법 (보안 주의)

22 August 2025·441 words·3 mins

Docker 외부 연결 TLS 암호화로 보호하기

22 August 2025·661 words·4 mins

Traefik 서비스 및 위젯 추가 (`services.yaml`)
#

이제 실제 대시보드에 표시될 Traefik 서비스를 추가합니다. config/services.yaml 파일을 열고 원하는 그룹에 아래 내용을 추가하십시오.

# config/services.yaml

- My Service: # 서비스 그룹 이름
    - Traefik:
        # 아이콘은 URL 또는 로컬 파일을 지정할 수 있습니다.
        icon: https://traefik.io/favicon.svg
        # 클릭 시 이동할 Traefik 대시보드 주소
        href: http://192.168.0.100:8080/
        description: Reverse Proxy
        # 1단계에서 설정한 Docker 서버 이름 (로컬이라면 my-docker)
        server: my-docker
        # 상태를 확인할 Docker 컨테이너 이름
        container: traefik
        # Traefik 통계 위젯 설정
        widget:
          type: traefik
          url: http://192.168.0.100:8080/
          # Traefik API/대시보드에 Basic Auth가 설정된 경우
          # user: your_username
          # pass: your_password

server: 1단계의 docker.yaml에서 정의한 Docker 연결의 이름(예: my-docker)을 정확히 입력합니다. 이를 통해 Homepage는 해당 Docker 호스트에서 컨테이너를 찾습니다.
container: 상태를 추적할 Traefik 컨테이너의 이름을 지정합니다.
widget:
- type: traefik으로 지정하여 Traefik 위젯을 활성화합니다.
- url: Traefik의 API 엔드포인트가 포함된 대시보드 주소를 입력합니다. (보통 http://서버IP:8080/)
- user / pass: (선택 사항) Traefik 대시보드에 Basic Authentication(기본 인증)이 설정된 경우, 해당 사용자 이름과 비밀번호를 입력해야 위젯이 정상적으로 데이터를 가져올 수 있습니다.

결과 확인
#

docker.yaml과 services.yaml 파일 수정을 완료하고 저장하면, Homepage는 자동으로 설정을 다시 읽어옵니다. 별도의 재시작 없이 대시보드 웹페이지를 새로고침하면 변경사항이 적용됩니다.

위와 같이 “My Service” 그룹에 Traefik 서비스가 추가되고, 컨테이너가 정상 실행 중임을 나타내는 상태 아이콘과 함께 현재 활성화된 HTTP 라우터 및 서비스 개수가 위젯에 표시되면 성공입니다.

마무리하며
#

이것으로 Homepage 대시보드에 핵심 인프라인 Traefik의 상태와 통계를 연동하는 과정이 완료되었습니다. 이와 같은 방식으로 다른 주요 서비스들을 하나씩 추가하여, 나만의 강력하고 직관적인 서버 통합 관리 대시보드를 구축해 보시기 바랍니다.

참조

Homepage 공식 문서 - Traefik Widget: https://gethomepage.dev/latest/widgets/services/traefik/
Homepage 공식 문서 - Docker Integration: https://gethomepage.dev/latest/configs/docker/

Docker 연동 설정 (docker.yaml)#

Homepage와 Traefik이 동일한 서버에 있는 경우#

Homepage와 Traefik이 다른 서버에 있는 경우#

Traefik 서비스 및 위젯 추가 (services.yaml)#

결과 확인#

마무리하며#