Homepage: 개발자를 위한 모던 서비스 대시보드

---

100개 이상의 서비스 통합과 Docker 자동 감지를 지원하는 고성능 애플리케이션 런처

---

개요

Homepage는 빠르고 안전하며 고도로 커스터마이징 가능한 서비스 대시보드입니다. YAML 파일로 간단히 설정하고, Docker 라벨을 통한 자동 서비스 감지, 100개 이상의 서비스 위젯 통합을 지원합니다. Next.js 기반으로 정적 생성되어 로딩이 빠르고, API 키가 프록시되어 보안이 뛰어납니다.

항목	내용
공식 사이트	https://gethomepage.dev
GitHub	https://github.com/gethomepage/homepage
라이선스	GNU GPL v3.0
GitHub Stars	21k+
Docker 이미지	ghcr.io/gethomepage/homepage:latest
기반 기술	Next.js, React, Tailwind CSS

---

왜 Homepage인가?

1. 빠름 (Fast)

Next.js 정적 생성으로 즉시 로딩됩니다. 서버사이드 렌더링 없이 빌드 시점에 페이지가 생성됩니다.

2. 안전함 (Secure)

모든 API 요청이 백엔드를 통해 프록시됩니다. API 키가 브라우저에 노출되지 않습니다.

3. Docker 네이티브

Docker 라벨만 추가하면 서비스가 자동으로 대시보드에 나타납니다. 별도 설정 파일 수정 없이 컨테이너 상태와 리소스 사용량을 확인할 수 있습니다.

4. 풍부한 위젯

100개 이상의 서비스 위젯을 기본 지원합니다. Plex, Sonarr, Radarr, Home Assistant, Pi-hole, Proxmox 등 대부분의 셀프호스팅 앱을 지원합니다.

5. 다국어 지원

40개 이상 언어를 지원합니다. 한국어도 포함되어 있습니다.

---

Homepage vs 다른 대시보드

항목	Homepage	Homarr	Dashy
설정 방식	YAML	드래그앤드롭 UI	YAML + UI
Docker 자동 감지	✅ 라벨 기반	⚠️ 제한적	❌
서비스 위젯	100개+	30개+	50개+
API 프록시	✅	❌	❌
성능	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐
학습 곡선	중간 (YAML)	낮음	중간
커스텀 API	✅ 강력함	⚠️ 제한적	⚠️ 제한적
추천 대상	개발자, DevOps	일반 사용자	고급 커스터마이징

Homepage 선택이 좋은 경우:

• Docker 환경에서 자동 서비스 감지가 필요할 때
• API 키 보안이 중요할 때
• YAML 기반 설정으로 버전 관리(Git)가 필요할 때
• 다양한 서비스의 상태/데이터를 한눈에 보고 싶을 때

---

Docker Compose로 설치하기

기본 설치

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      HOMEPAGE_ALLOWED_HOSTS: homepage.local  # 또는 "*" (개발용)
      PUID: 1000
      PGID: 1000
    ports:
      - 3000:3000
    volumes:
      - ./config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro  # Docker 통합용
    restart: unless-stopped

설치 및 실행

# 디렉토리 생성
mkdir -p ~/homepage/config && cd ~/homepage

# docker-compose.yml 파일 생성 후
docker compose up -d

# 초기 설정 파일 확인
ls config/
# bookmarks.yaml  docker.yaml  services.yaml  settings.yaml  widgets.yaml

브라우저에서 http://<서버IP>:3000으로 접속합니다.

---

설정 파일 구조

Homepage는 5개의 YAML 파일로 구성됩니다.

config/
├── services.yaml    # 서비스 및 위젯 정의
├── widgets.yaml     # 상단 정보 위젯 (날씨, 검색 등)
├── bookmarks.yaml   # 북마크 링크
├── settings.yaml    # 전역 설정 (테마, 레이아웃 등)
└── docker.yaml      # Docker 연결 설정

---

서비스 설정 (services.yaml)

기본 서비스 추가

# services.yaml
- 미디어:
    - Plex:
        icon: plex.png
        href: http://plex.local:32400
        description: 미디어 서버

    - Jellyfin:
        icon: jellyfin.png
        href: http://jellyfin.local:8096
        description: 오픈소스 미디어 서버

- 인프라:
    - Portainer:
        icon: portainer.png
        href: http://portainer.local:9000
        description: Docker 관리

    - Proxmox:
        icon: proxmox.png
        href: https://proxmox.local:8006
        description: 가상화 플랫폼

서비스 위젯 추가

- 미디어:
    - Plex:
        icon: plex.png
        href: http://plex.local:32400
        description: 미디어 서버
        widget:
          type: tautulli
          url: http://tautulli.local:8181
          key: your-tautulli-api-key

    - Sonarr:
        icon: sonarr.png
        href: http://sonarr.local:8989
        description: TV 시리즈 관리
        widget:
          type: sonarr
          url: http://sonarr.local:8989
          key: your-sonarr-api-key
          fields: ["wanted", "queued", "series"]

Docker 컨테이너 상태 표시

- 인프라:
    - Portainer:
        icon: portainer.png
        href: http://portainer.local:9000
        server: my-docker  # docker.yaml에 정의된 서버
        container: portainer  # 컨테이너 이름

---

Docker 자동 감지 설정

docker.yaml 설정

# docker.yaml
my-docker:
  socket: /var/run/docker.sock

컨테이너 라벨로 서비스 추가

Docker Compose에서 라벨만 추가하면 자동으로 Homepage에 나타납니다.

# 예: Jellyfin docker-compose.yml
services:
  jellyfin:
    image: jellyfin/jellyfin
    container_name: jellyfin
    ports:
      - 8096:8096
    labels:
      - homepage.group=미디어
      - homepage.name=Jellyfin
      - homepage.icon=jellyfin.png
      - homepage.href=http://jellyfin.local:8096
      - homepage.description=오픈소스 미디어 서버
      - homepage.widget.type=jellyfin
      - homepage.widget.url=http://jellyfin:8096
      - homepage.widget.key=your-api-key

컨테이너 리소스 표시

settings.yaml에서 활성화:

# settings.yaml
showStats: true

이제 각 서비스 카드에서 CPU, 메모리, 네트워크 사용량을 확인할 수 있습니다.

---

정보 위젯 (widgets.yaml)

상단에 표시되는 시스템 정보, 날씨, 검색 등을 설정합니다.

# widgets.yaml
- resources:
    label: 시스템
    cpu: true
    memory: true
    disk: /

- resources:
    label: 저장소
    disk:
      - /mnt/data
      - /mnt/backup

- search:
    provider: google
    target: _blank

- datetime:
    text_size: xl
    format:
      dateStyle: long
      timeStyle: short
      hour12: false

- openweathermap:
    label: 서울
    latitude: 37.5665
    longitude: 126.9780
    units: metric
    apiKey: your-openweathermap-api-key

---

주요 서비스 위젯

미디어

위젯	표시 정보
Plex / Tautulli	현재 스트리밍, 사용자 수
Jellyfin	현재 재생, 세션 수
Sonarr	원하는 에피소드, 큐, 시리즈 수
Radarr	원하는 영화, 큐, 영화 수
qBittorrent	다운로드/업로드 속도, 시드 수

인프라

위젯	표시 정보
Proxmox	노드 상태, VM/컨테이너 수, 리소스
Portainer	컨테이너 상태, 스택 수
Traefik	라우터, 서비스, 미들웨어 수
Nginx Proxy Manager	프록시 호스트, 리디렉션 수
Pi-hole / AdGuard	쿼리 수, 차단률

모니터링

위젯	표시 정보
Uptime Kuma	서비스 상태, 업타임
Glances	CPU, 메모리, 네트워크
Prometheus	커스텀 쿼리 결과

스마트홈

위젯	표시 정보
Home Assistant	엔티티 상태
OpenHAB	아이템 상태

---

Custom API 위젯

내장되지 않은 서비스도 Custom API 위젯으로 연동할 수 있습니다.

기본 사용법

- 모니터링:
    - 내 서비스:
        icon: mdi-api
        href: http://myservice.local
        widget:
          type: customapi
          url: http://myservice.local/api/status
          method: GET
          refreshInterval: 10000  # 10초
          mappings:
            - field: users
              label: 사용자
              format: number
            - field: status
              label: 상태
              format: text

API 응답 예시

{
  "users": 42,
  "status": "running",
  "uptime": 99.9
}

중첩 필드 접근

widget:
  type: customapi
  url: http://api.example.com/stats
  mappings:
    - field:
        data:
          metrics:
            cpu: usage
      label: CPU
      format: percent

값 변환 (Remap)

widget:
  type: customapi
  url: http://api.example.com/status
  mappings:
    - field: status
      label: 상태
      format: text
      remap:
        - value: 0
          to: 오프라인
        - value: 1
          to: 온라인
        - any: true
          to: 알 수 없음

리스트 표시 (Dynamic List)

widget:
  type: customapi
  url: http://api.example.com/servers
  display: dynamic-list
  mappings:
    items: data  # 배열 경로
    name: hostname
    label: ip_address
    limit: 5

---

레이아웃 커스터마이징

settings.yaml

# settings.yaml
title: My Homelab

# 배경 이미지
background:
  image: https://images.unsplash.com/photo-xxx
  blur: sm
  opacity: 50

# 테마
theme: dark
color: slate

# 파비콘
favicon: https://example.com/favicon.ico

# 레이아웃 (컬럼 수)
layout:
  미디어:
    style: row
    columns: 4
  인프라:
    style: row
    columns: 3

# 헤더 스타일
headerStyle: boxed

# 컨테이너 상태 표시
showStats: true

# 상태 표시 스타일
statusStyle: dot

탭 기반 레이아웃

# settings.yaml
layout:
  - name: 서버
    tab: 인프라
  - name: 스토리지
    tab: 인프라
  - name: 영화
    tab: 미디어
  - name: TV
    tab: 미디어

---

북마크 설정 (bookmarks.yaml)

# bookmarks.yaml
- 개발:
    - GitHub:
        - icon: github.png
          href: https://github.com
    - Stack Overflow:
        - icon: stackoverflow.png
          href: https://stackoverflow.com

- 클라우드:
    - AWS Console:
        - icon: aws.png
          href: https://console.aws.amazon.com
    - GCP Console:
        - icon: google-cloud.png
          href: https://console.cloud.google.com

- 참고자료:
    - Docker Hub:
        - icon: docker.png
          href: https://hub.docker.com
    - Self-Hosted:
        - icon: mdi-server
          href: https://github.com/awesome-selfhosted/awesome-selfhosted

---

보안 설정

HOMEPAGE_ALLOWED_HOSTS

Homepage는 Host 헤더를 검증합니다. 프로덕션에서는 반드시 설정하세요.

environment:
  HOMEPAGE_ALLOWED_HOSTS: homepage.yourdomain.com,192.168.1.100:3000

리버스 프록시 뒤에서 사용

Homepage는 자체 인증 기능이 없습니다. Nginx Proxy Manager, Traefik, Authelia 등과 함께 사용하세요.

# Traefik 라벨 예시
labels:
  - traefik.enable=true
  - traefik.http.routers.homepage.rule=Host(`home.yourdomain.com`)
  - traefik.http.routers.homepage.middlewares=authelia@docker

Docker 소켓 보안

Docker 소켓 직접 마운트 대신 docker-socket-proxy 사용을 권장합니다.

services:
  dockerproxy:
    image: tecnativa/docker-socket-proxy
    container_name: dockerproxy
    environment:
      - CONTAINERS=1
      - SERVICES=1
      - INFO=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - 2375:2375
    restart: unless-stopped

  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    # docker.sock 마운트 제거
    # ...

# docker.yaml
my-docker:
  host: dockerproxy
  port: 2375

---

환경 변수로 비밀값 관리

YAML 파일에 직접 API 키를 넣지 않고 환경 변수로 관리할 수 있습니다.

.env 파일

# .env
PLEX_API_KEY=abcdef123456
SONARR_API_KEY=xyz789
WEATHER_API_KEY=weather123

docker-compose.yml

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    env_file:
      - .env
    # ...

services.yaml에서 사용

- 미디어:
    - Plex:
        widget:
          type: tautulli
          url: http://tautulli:8181
          key: {{HOMEPAGE_VAR_PLEX_API_KEY}}

환경 변수 이름에 HOMEPAGE_VAR_ 접두사를 붙이면 YAML에서 {{HOMEPAGE_VAR_...}} 형식으로 참조할 수 있습니다.

---

Kubernetes 지원

Homepage는 Kubernetes Ingress 어노테이션을 통한 자동 서비스 감지도 지원합니다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: jellyfin
  annotations:
    gethomepage.dev/enabled: "true"
    gethomepage.dev/group: 미디어
    gethomepage.dev/name: Jellyfin
    gethomepage.dev/icon: jellyfin.png
    gethomepage.dev/description: 미디어 서버
spec:
  rules:
    - host: jellyfin.local
      # ...

---

트러블슈팅

위젯이 데이터를 표시하지 않음

1. API 키가 올바른지 확인
2. Homepage 컨테이너에서 서비스에 접근 가능한지 확인
3. 컨테이너 로그 확인: docker logs homepage

Docker 컨테이너가 감지되지 않음

1. docker.yaml에 서버가 정의되어 있는지 확인
2. Docker 소켓이 마운트되어 있는지 확인
3. 라벨 문법이 올바른지 확인 (점 표기법: homepage.group)

CORS 오류

Homepage가 프록시 역할을 하므로 CORS 오류는 발생하지 않아야 합니다. 발생한다면 위젯 URL이 브라우저에서 직접 호출되고 있는 것입니다.

---

마무리

Homepage는 개발자와 홈랩 운영자를 위한 최고의 서비스 대시보드입니다. YAML 기반 설정으로 버전 관리가 쉽고, Docker 라벨을 통한 자동 서비스 감지, API 키 프록시를 통한 보안, 100개 이상의 서비스 위젯 등 강력한 기능을 제공합니다.

특히 Custom API 위젯을 활용하면 어떤 서비스든 대시보드에 통합할 수 있어, 모든 인프라를 한눈에 모니터링하는 단일 진입점으로 활용하기 좋습니다.

---