Homepage: Das Dashboard für dein Homelab

Du hast 20, 30 oder noch mehr Services in deinem Homelab laufen. Proxmox-VMs, Docker-Container, Media-Server, Monitoring-Tools. Aber keinen Überblick. Du springst zwischen Browser-Tabs hin und her, merkst dir IP-Adressen und Port-Nummern, verlierst den Überblick. Es muss einen besseren Weg geben. Genau hier kommt Homepage ins Spiel: Ein schlankes, blitzschnelles Dashboard, das all deine Services an einem Ort zusammenführt und dabei noch verdammt gut aussieht.

---

Was ist Homepage?

Homepage ist ein Open-Source-Dashboard, das speziell für Homelabs und Self-Hosted-Umgebungen entwickelt wurde. Im Gegensatz zu einfachen Bookmark-Seiten bietet Homepage echte Integration mit deinen Services: Live-Status, Statistiken, API-Anbindungen. Das Projekt wird aktiv auf GitHub entwickelt und hat sich in den letzten Jahren zur ersten Wahl für viele Homelab-Enthusiasten entwickelt.

Die Stärken auf einen Blick:

• Geschrieben in Next.js, lädt in Millisekunden
• Über 100 vorgefertigte Service-Widgets mit API-Integration
• YAML-basierte Konfiguration, versionierbar mit Git
• Docker-native mit automatischer Container-Erkennung via Labels
• Keine Datenbank erforderlich
• Themable und anpassbar bis ins Detail

Homepage ist nicht nur eine Linksammlung, sondern ein vollwertiges Monitoring-Dashboard. Du siehst auf einen Blick: Läuft Plex? Wie viele Downloads hat Sonarr? Wie ausgelastet ist Proxmox?

---

Features im Überblick

Homepage bringt eine beeindruckende Feature-Liste mit, die weit über simple Bookmarks hinausgeht:

Service-Widgets: Über 100 vorgefertigte Integrationen für populäre Self-Hosted-Services. Proxmox, Sonarr, Radarr, Jellyfin, Pi-hole, Home Assistant, Portainer, GitLab, Nextcloud und viele mehr. Jedes Widget zeigt relevante Live-Daten: CPU-Auslastung, aktive Downloads, User-Counts, API-Status.

Docker-Integration: Homepage kann direkt mit dem Docker-Socket kommunizieren und Container automatisch erkennen. Via Docker-Labels konfigurierst du Services, ohne die YAML-Config anzufassen. Besonders praktisch in dynamischen Umgebungen.

Bookmarks: Klassische Lesezeichen-Gruppen für Webseiten ohne API-Integration. GitHub, Reddit, Monitoring-Dashboards, dokumentation.

System-Info-Widgets: CPU, RAM, Disk, Network-Traffic deines Hosts. Auch für Remote-Hosts via SSH oder API.

Wetter-Widget: Lokales Wetter via OpenMeteo-API, keine Registrierung nötig.

Suchleiste: Quick-Launch für alle Services plus Integration mit Google, DuckDuckGo, Custom-Search-Engines.

Tastatur-Navigation: Spotlight-artige Suche mit Strg+K, perfekt für Power-User.

Custom CSS: Vollständig themable. Dark Mode, Light Mode, Custom Colors.

Multi-Language: Deutsche UI verfügbar.

Kubernetes-Support: Für größere Setups mit K8s-Clustern.

Die Widget-Liste wächst kontinuierlich. Fehlt dein Lieblings-Service? Die Community ist aktiv, neue Integrationen werden regelmäßig hinzugefügt. Alternativ kannst du Custom-API-Widgets nutzen.

---

Installation

Die Installation ist denkbar einfach. Homepage läuft am besten als Docker-Container. Hier eine minimale docker-compose.yml:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3000:3000
    volumes:
      - ./homepage:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - TZ=Europe/Berlin
      - PUID=1000
      - PGID=1000
    restart: unless-stopped

Einige wichtige Punkte zur Compose-Datei:

• Port 3000: Standard-Port für Homepage. Du kannst ihn natürlich anpassen.
• Volume ./homepage: Hier liegen die Konfig-Dateien. Wird automatisch angelegt.
• Docker-Socket: Read-Only-Zugriff auf /var/run/docker.sock ermöglicht Docker-Integration.
• Timezone: Wichtig für korrekte Zeitanzeigen in Widgets.
• PUID/PGID: User- und Group-ID für Dateiberechtigungen.

Nach dem ersten Start erstellt Homepage automatisch die nötigen Config-Dateien:

homepage/
├── bookmarks.yaml     # Lesezeichen-Gruppen
├── docker.yaml        # Docker-Integration-Config
├── services.yaml      # Service-Definitionen mit Widgets
├── settings.yaml      # Globale Einstellungen (Theme, Layout)
├── widgets.yaml       # Dashboard-Widgets (CPU, Wetter, etc.)
└── custom.css         # Optionales Custom-Styling

Der erste Aufruf von http://localhost:3000 zeigt dir ein leeres Dashboard mit Beispiel-Config. Zeit zum Konfigurieren.

Docker-Socket-Zugriff ist mächtig. In Produktivumgebungen solltest du einen Docker-Socket-Proxy wie Tecnativa/docker-socket-proxy verwenden, um den Zugriff einzuschränken.

---

Konfiguration: settings.yaml

Die settings.yaml ist das Herzstück der globalen Einstellungen. Hier legst du Theme, Layout und generelle Optionen fest:

title: Homelab Dashboard
favicon: https://gethomepage.dev/img/favicon.ico

theme: dark
color: slate

headerStyle: boxed
layout:
  Infrastruktur:
    style: row
    columns: 3
  Media:
    style: row
    columns: 4
  Entwicklung:
    style: row
    columns: 2

quicklaunch:
  searchDescriptions: true
  hideInternetSearch: false
  hideVisitURL: false

background:
  image: /images/background.png
  blur: sm
  saturate: 50
  brightness: 50
  opacity: 20

cardBlur: md

language: de

providers:
  openweathermap: openweathermapapikey
  weatherapi: weatherapiapikey

hideErrors: false
showStats: true

Die wichtigsten Optionen im Detail:

Theme und Color: Homepage bietet mehrere Themes (dark, light) und Farbpaletten (slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose). Experimentiere mit Kombinationen.

Layout: Definiere pro Service-Gruppe Style und Spaltenanzahl. row für horizontales Layout, column für vertikales. Praktisch für unterschiedliche Service-Typen.

Quicklaunch: Die Suchleiste. searchDescriptions durchsucht auch Service-Beschreibungen, nicht nur Namen.

Background: Custom-Background-Image mit Blur, Saturate, Brightness, Opacity. Für dezente Hintergründe.

Language: de für deutsches Interface.

Nutze cardBlur für einen Glasmorphism-Effekt auf Service-Cards. Sieht mit Background-Images besonders gut aus.

---

Konfiguration: services.yaml

Die services.yaml definiert deine Services, gruppiert und mit Widget-Integration. Hier ein Beispiel aus einem echten Homelab:

---
- Infrastruktur:
    - Proxmox:
        icon: proxmox.png
        href: https://192.168.60.15:8006
        description: Virtualisierung
        widget:
          type: proxmox
          url: https://192.168.60.15:8006
          username: monitoring@pve
          password: monitoring-password

    - Pi-hole:
        icon: pi-hole.png
        href: http://192.168.2.20/admin
        description: DNS Adblocker
        widget:
          type: pihole
          url: http://192.168.2.20
          key: pihole-api-key

    - Nginx Proxy Manager:
        icon: nginx-proxy-manager.png
        href: https://192.168.60.65
        description: Reverse Proxy
        widget:
          type: npm
          url: http://192.168.60.65:81
          username: [email protected]
          password: npm-password

    - Portainer:
        icon: portainer.png
        href: https://portainer.newsxc.net
        description: Docker Management
        widget:
          type: portainer
          url: http://192.168.60.100:9000
          env: 1
          key: portainer-api-key

- Media:
    - Jellyfin:
        icon: jellyfin.png
        href: https://jellyfin.newsxc.net
        description: Media Server
        widget:
          type: jellyfin
          url: http://192.168.60.80:8096
          key: jellyfin-api-key
          enableBlocks: true
          enableNowPlaying: true

    - Sonarr:
        icon: sonarr.png
        href: https://sonarr.newsxc.net
        description: TV Shows
        widget:
          type: sonarr
          url: http://192.168.60.85:8989
          key: sonarr-api-key
          enableQueue: true

    - Radarr:
        icon: radarr.png
        href: https://radarr.newsxc.net
        description: Filme
        widget:
          type: radarr
          url: http://192.168.60.85:7878
          key: radarr-api-key
          enableQueue: true

    - Prowlarr:
        icon: prowlarr.png
        href: https://prowlarr.newsxc.net
        description: Indexer Manager
        widget:
          type: prowlarr
          url: http://192.168.60.85:9696
          key: prowlarr-api-key

- Entwicklung:
    - GitLab:
        icon: gitlab.png
        href: https://gitlab.newsxc.net
        description: Git Repository
        widget:
          type: gitlab
          url: https://gitlab.newsxc.net
          key: gitlab-api-key

    - Gitea:
        icon: gitea.png
        href: https://gitea.newsxc.net
        description: Leichtgewichtige Git-Forge

    - Code Server:
        icon: code-server.png
        href: https://code.newsxc.net
        description: VS Code im Browser

Die Struktur ist selbsterklärend:

1. Gruppen: Top-Level sind Gruppen (z.B. Infrastruktur, Media). Diese korrespondieren mit den Layout-Einstellungen in settings.yaml.

2. Services: Jeder Service hat Name, Icon, URL, Beschreibung.

3. Widget: Optional, aber das macht Homepage mächtig. Über 100 Widget-Typen verfügbar. Wichtigste Parameter:

   • type: Widget-Typ (proxmox, pihole, sonarr, etc.)
   • url: API-Endpoint des Services
   • key: API-Key (bei Auth-pflichtigen APIs)
   • username/password: Basic Auth oder Service-spezifische Credentials
   • Widget-spezifische Optionen (z.B. enableQueue bei Sonarr)

API-Keys findest du meist in den Einstellungen deiner Services. Proxmox benötigt einen dedizierten Monitoring-User. Pi-hole zeigt den API-Key in Settings → API. Sonarr/Radarr unter Settings → General → API Key.

---

Konfiguration: widgets.yaml

Die widgets.yaml definiert Dashboard-weite Widgets, die nicht zu einzelnen Services gehören. Denk an System-Info, Wetter, Suche:

---
- logo:
    icon: https://gethomepage.dev/img/favicon.ico

- search:
    provider: google
    target: _blank
    showSearchSuggestions: true

- datetime:
    text_size: xl
    format:
      timeStyle: short
      dateStyle: short
      hourCycle: h23

- openmeteo:
    label: Berlin
    latitude: 52.52
    longitude: 13.40
    units: metric
    cache: 5
    timezone: Europe/Berlin

- resources:
    cpu: true
    memory: true
    disk: /
    cputemp: true
    uptime: true
    units: metric
    refresh: 3000

- resources:
    label: NAS
    cpu: true
    memory: true
    disk: /mnt/storage
    expanded: true
    units: metric
    refresh: 5000

Die Widget-Typen im Detail:

Logo: Zeigt ein Logo oder Icon oben im Dashboard.

Search: Suchleiste mit Provider-Auswahl (Google, DuckDuckGo, Brave, Custom). showSearchSuggestions aktiviert Live-Suggestions.

Datetime: Datum und Uhrzeit. Formatierung via Intl-Optionen. hourCycle: h23 für 24-Stunden-Format.

Openmeteo: Wetter-Widget via OpenMeteo-API (kostenlos, keine Registrierung). Latitude/Longitude deines Standorts. cache in Minuten.

Resources: System-Ressourcen. CPU, Memory, Disk, CPU-Temp, Uptime. disk nimmt Mount-Point (z.B. /, /mnt/data). Du kannst mehrere Resources-Widgets für verschiedene Hosts definieren (via label).

Für Remote-Hosts (NAS, andere Server) kannst du resources mit SSH-Zugriff oder Custom-APIs kombinieren. Alterativ nutze Node-Exporter + Prometheus und baue Custom-Widgets.

---

Konfiguration: bookmarks.yaml

Für Services ohne Widget-Integration oder einfache Webseiten nutzt du Bookmarks:

---
- Entwicklung:
    - GitHub:
        - icon: github.png
          href: https://github.com
          description: Code Repository

    - Stack Overflow:
        - icon: stackoverflow.png
          href: https://stackoverflow.com
          description: Q&A Community

    - DevDocs:
        - icon: devdocs.png
          href: https://devdocs.io
          description: API Documentation

- Social:
    - Reddit r/selfhosted:
        - icon: reddit.png
          href: https://reddit.com/r/selfhosted
          description: Self-Hosting Community

    - Hacker News:
        - icon: hackernews.png
          href: https://news.ycombinator.com
          description: Tech News

- Tools:
    - regex101:
        - icon: regex101.png
          href: https://regex101.com
          description: Regex Tester

    - JSON Formatter:
        - icon: json.png
          href: https://jsonformatter.org
          description: JSON Tools

    - CyberChef:
        - icon: cyberchef.png
          href: https://gchq.github.io/CyberChef/
          description: Data Transformation

- Monitoring:
    - Uptime Kuma:
        - icon: uptime-kuma.png
          href: https://uptime.newsxc.net
          description: Uptime Monitoring

    - Grafana:
        - icon: grafana.png
          href: https://grafana.newsxc.net
          description: Metrics Dashboard

Bookmarks sind einfach strukturiert: Gruppen, dann Services mit Icon, URL, Beschreibung. Kein Widget-Support, aber dafür null Config-Aufwand. Perfekt für statische Links.

---

Docker-Integration via Labels

Einer der cleversten Features von Homepage ist die Docker-Label-Integration. Statt Services in services.yaml zu definieren, annotierst du deine Container mit Labels. Homepage erkennt sie automatisch.

Beispiel: Ein Nginx Proxy Manager-Container mit Homepage-Labels:

services:
  npm:
    image: jc21/nginx-proxy-manager:latest
    container_name: nginx-proxy-manager
    ports:
      - "80:80"
      - "443:443"
      - "81:81"
    volumes:
      - ./npm/data:/data
      - ./npm/letsencrypt:/etc/letsencrypt
    labels:
      - "homepage.group=Infrastruktur"
      - "homepage.name=Nginx Proxy Manager"
      - "homepage.icon=nginx-proxy-manager.png"
      - "homepage.href=https://npm.newsxc.net"
      - "homepage.description=Reverse Proxy & SSL"
      - "homepage.widget.type=npm"
      - "homepage.widget.url=http://npm:81"
      - "[email protected]"
      - "homepage.widget.password=npm-password"

Das gleiche Prinzip funktioniert mit jedem Container. Hier ein Traefik-Beispiel:

services:
  traefik:
    image: traefik:v2.10
    container_name: traefik
    labels:
      - "homepage.group=Infrastruktur"
      - "homepage.name=Traefik"
      - "homepage.icon=traefik.png"
      - "homepage.href=https://traefik.newsxc.net"
      - "homepage.description=Reverse Proxy & Load Balancer"
      - "homepage.widget.type=traefik"
      - "homepage.widget.url=http://traefik:8080"

Die Label-Syntax:

• homepage.group: Service-Gruppe (entspricht Gruppen in services.yaml)
• homepage.name: Service-Name
• homepage.icon: Icon-Datei (aus Icon-Pack oder URL)
• homepage.href: Externe URL zum Service
• homepage.description: Beschreibung
• homepage.widget.type: Widget-Typ
• homepage.widget.url: Widget-API-URL
• homepage.widget.key: API-Key (für Auth-pflichtige Widgets)
• homepage.widget.*: Weitere Widget-spezifische Parameter

Damit Homepage Docker-Container erkennt, brauchst du noch die docker.yaml:

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

Oder für Remote-Docker-Hosts:

---
docker:
  local:
    socket: /var/run/docker.sock

  remote-host:
    host: 192.168.60.100
    port: 2375

Docker-API über TCP (Port 2375) ist unsicher. Nutze TLS (Port 2376) mit Zertifikaten oder einen Socket-Proxy. Niemals ungeschützten Docker-Socket im Netzwerk exposen.

Vorteile der Label-Methode:

• Dezentrale Config: Service-Definition direkt beim Container
• Dynamische Discovery: Neue Container werden automatisch erkannt
• Weniger Config-Dateien zu pflegen
• Ideal für Stacks mit vielen Containern

Nachteile:

• Weniger Übersicht: Config verteilt über viele Compose-Dateien
• Erfordert Container-Restart bei Label-Änderungen
• Nicht für Non-Docker-Services (VMs, Bare-Metal)

Kombination möglich: Nutze Labels für Docker-Services, services.yaml für VMs und Bare-Metal-Services. Homepage merged beide Quellen.

---

Layout und Design

Homepage ist hochgradig anpassbar. Neben den Theme-Optionen in settings.yaml kannst du Custom-CSS nutzen.

Beispiel: Eigenes custom.css für Dark-Theme-Tweaks:

/* Dunkleres Background für Glasmorphism */
body {
  --background-opacity: 0.1;
}

/* Accent-Color für Links */
a {
  color: #60a5fa;
}

a:hover {
  color: #93c5fd;
}

/* Service-Cards mit mehr Schatten */
.service-card {
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.3), 0 2px 4px -1px rgba(0, 0, 0, 0.2);
}

/* Widget-Text größer */
.widget-text {
  font-size: 1.1rem;
}

/* Custom-Background für spezifische Gruppen */
[data-group="Media"] {
  background: linear-gradient(135deg, rgba(99, 102, 241, 0.1) 0%, rgba(139, 92, 246, 0.1) 100%);
  border-radius: 0.5rem;
  padding: 1rem;
}

Das Custom-CSS muss im Config-Volume liegen (./homepage/custom.css). Homepage lädt es automatisch.

Layout-Optionen in settings.yaml:

layout:
  Infrastruktur:
    style: row         # Horizontales Layout
    columns: 3         # 3 Spalten

  Media:
    style: column      # Vertikales Layout
    columns: 2         # 2 Spalten

  Entwicklung:
    style: row
    columns: 4
    header: false      # Gruppe ohne Header

Tab-Layout:

Für sehr viele Services kannst du Tab-Layout nutzen. Jede Gruppe wird ein Tab:

layout:
  style: tabs
  tabs:
    - Infrastruktur
    - Media
    - Entwicklung
    - Monitoring

Background-Images:

background:
  image: /images/homelab-bg.jpg
  blur: md
  saturate: 100
  brightness: 50
  opacity: 30

Das Image muss im homepage/public/images/ Ordner liegen.

Für professionelle Background-Images schau dir Unsplash oder Pexels an. Suche nach “server room”, “data center”, “circuit board” für Homelab-Vibe.

---

Vergleich: Homepage vs. Homarr vs. Dashy vs. Heimdall

Homepage ist nicht die einzige Dashboard-Lösung. Hier ein Vergleich mit populären Alternativen:

Feature	Homepage	Homarr	Dashy	Heimdall
Service-Widgets	100+ mit Live-Daten	50+ mit Live-Daten	Ping-Status nur	Ping-Status nur
Docker-Integration	Native via Labels	Native via Labels	Nein	Nein
Konfiguration	YAML-Dateien	Web-UI + JSON	YAML oder Web-UI	Web-UI + DB
Bookmarks	Ja	Ja	Ja	Ja
Suchleiste	Ja, mit Providern	Ja	Ja	Nein
System-Widgets	CPU, RAM, Disk, Temp	CPU, RAM, Disk	Nein	Nein
Custom CSS	Ja	Ja	Ja	Begrenzt
Themes	Dark/Light + Colors	Dark/Light + Custom	20+ Themes	Dark/Light
Kubernetes	Ja	Nein	Nein	Nein
Performance	Exzellent (Next.js)	Sehr gut (React)	Gut (Vue)	Gut (PHP)
Mobile-UI	Responsive	Responsive	Responsive	Responsive
Auth	Reverse-Proxy	Integriert	Integriert	Integriert
Datenbank	Keine	Keine	Keine	SQLite
Aktive Entwicklung	Sehr aktiv	Sehr aktiv	Aktiv	Wenig aktiv
Community	Groß	Wachsend	Groß	Mittel

Zusammenfassung:

• Homepage: Beste Wahl für Live-Monitoring und Docker-Integration. YAML-Config perfekt für Git-Versioning. Schnellste Performance.

• Homarr: Ähnlich Homepage, aber mit Web-UI-Config. Gut für User, die YAML scheuen. Weniger Widgets als Homepage.

• Dashy: Feature-reich, viele Themes, aber keine echten Service-Widgets. Gut für reine Bookmark-Dashboards.

• Heimdall: Simpel, solide, aber wenig aktive Entwicklung. Keine Widget-Integration. Eher Legacy.

Meine Empfehlung: Homepage für Power-User mit vielen Services. Homarr für Einsteiger mit Web-UI-Präferenz. Dashy für Design-Fokus ohne Monitoring-Bedarf.

---

Widgets: Die Killer-Features

Der wahre Mehrwert von Homepage liegt in den Service-Widgets. Hier eine Auswahl der wichtigsten Integrations-Typen:

Infrastruktur

Proxmox: Zeigt Cluster-Status, VM/CT-Anzahl, CPU/RAM-Auslastung, Node-Status.

widget:
  type: proxmox
  url: https://192.168.60.15:8006
  username: monitoring@pve
  password: monitoring-password
  node: gandalf

Pi-hole: DNS-Queries, Blocked Percentage, Ads Blocked Today.

widget:
  type: pihole
  url: http://192.168.2.20
  key: pihole-api-key

Nginx Proxy Manager: Proxy Hosts, SSL Certificates, Redirections.

widget:
  type: npm
  url: http://192.168.60.65:81
  username: [email protected]
  password: npm-password

Portainer: Containers Running, Images, Volumes, Networks.

widget:
  type: portainer
  url: http://192.168.60.100:9000
  env: 1
  key: portainer-api-key

Media

Jellyfin: Users, Now Playing, Library Stats.

widget:
  type: jellyfin
  url: http://192.168.60.80:8096
  key: jellyfin-api-key
  enableBlocks: true
  enableNowPlaying: true

Sonarr/Radarr: Queue, Wanted, Calendar, Missing.

widget:
  type: sonarr
  url: http://192.168.60.85:8989
  key: sonarr-api-key
  enableQueue: true

Plex: Now Playing, Streams, Bandwidth.

widget:
  type: plex
  url: http://192.168.60.75:32400
  key: plex-token

Monitoring

Prometheus: Query Results als Metric.

widget:
  type: prometheus
  url: http://192.168.60.90:9090
  query: up{job="node"}

Grafana: Dashboards, Alerts.

widget:
  type: grafana
  url: http://192.168.60.91:3000
  username: admin
  password: grafana-password

Uptime Kuma: Monitor-Status, Uptime-Percentage.

widget:
  type: uptimekuma
  url: http://192.168.60.92:3001
  slug: uptime-slug

Development

GitLab: Projects, Issues, Merge Requests.

widget:
  type: gitlab
  url: https://gitlab.newsxc.net
  key: gitlab-api-key

GitHub: Repositories, Stars, Issues, PRs.

widget:
  type: github
  username: your-username
  key: github-token

Jenkins: Build Status, Queue.

widget:
  type: jenkins
  url: http://192.168.60.95:8080
  username: admin
  password: jenkins-password

Die vollständige Widget-Liste findest du in der Homepage-Dokumentation. Neue Widgets werden regelmäßig hinzugefügt. Check GitHub für aktuelle PRs.

---

Custom API Widgets

Dein Service hat kein fertiges Widget? Kein Problem. Homepage unterstützt Custom-API-Widgets mit JSONPath-Mapping:

- Custom Service:
    icon: custom.png
    href: http://192.168.60.200:8080
    description: Mein Custom-Service
    widget:
      type: customapi
      url: http://192.168.60.200:8080/api/stats
      mappings:
        - field: users
          label: Users
          format: number
        - field: requests
          label: Requests
          format: number
        - field: uptime
          label: Uptime
          format: text

Das Widget holt JSON von der URL und mappt Felder via JSONPath. format definiert die Darstellung (number, text, bytes, percent, date).

Für komplexere APIs mit Auth:

widget:
  type: customapi
  url: http://api.example.com/metrics
  method: POST
  headers:
    Authorization: Bearer your-token-here
    Content-Type: application/json
  body: '{"query": "stats"}'
  mappings:
    - field:
        data: cpu_usage
      label: CPU
      format: percent
    - field:
        data: memory_used
      label: RAM
      format: bytes

Custom-API-Widgets sind mächtig, erfordern aber Kenntnis der Service-API. Tools wie curl und jq helfen beim Testen der API-Antworten.

---

Tipps für die Praxis

Nach Monaten Homepage-Nutzung im echten Homelab haben sich diese Best Practices herauskristallisiert:

Git-Versionierung

Homepage-Configs sind YAML-Dateien. Perfekt für Git:

cd homepage
git init
git add .
git commit -m "Initial homepage config"
git remote add origin https://gitlab.newsxc.net/homelab/homepage.git
git push -u origin main

Vorteile: Änderungshistorie, Rollback bei Fehlern, Sync zwischen Hosts.

Erstelle ein .gitignore für sensitive Daten:

custom.css.bak
*.log
.env

Secrets via Environment Variables

API-Keys nicht direkt in YAML-Files. Nutze Environment-Variables:

widget:
  type: sonarr
  url: http://192.168.60.85:8989
  key: 

Im Docker-Compose:

environment:
  - HOMEPAGE_VAR_SONARR_KEY=actual-api-key-here

Oder via .env-File:

HOMEPAGE_VAR_SONARR_KEY=actual-api-key-here
HOMEPAGE_VAR_RADARR_KEY=another-key

Homepage ersetzt `` automatisch.

Docker-Socket-Proxy

Direkter Socket-Zugriff ist ein Sicherheitsrisiko. Nutze Tecnativa Docker-Socket-Proxy:

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

  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    depends_on:
      - docker-proxy
    environment:
      - DOCKER_HOST=docker-proxy:2375

Der Proxy limitiert API-Zugriff (read-only, nur Container-Info).

Icons: Dashboard-Icons-Repository

Homepage nutzt das walkxcode/dashboard-icons Repository. Über 1000 Service-Icons verfügbar.

Icon-Verwendung:

icon: sonarr.png          # Aus Dashboard-Icons
icon: mdi-server          # Material Design Icons
icon: https://example.com/icon.png  # Custom-URL
icon: /images/custom.png  # Lokales File in public/images/

Für Custom-Icons: Lege sie in homepage/public/images/ ab.

Responsive Design

Homepage ist mobile-responsive, aber für sehr viele Services wird’s eng. Tipps:

• Nutze Tab-Layout für viele Gruppen
• Reduziere Spaltenanzahl auf Mobile (Homepage passt automatisch an)
• Verstecke weniger wichtige Services via hideHeader: true

Performance-Optimierung

Bei vielen Widgets (30+) kann Homepage langsam werden:

• Widget-Caching: Setze cache in Widget-Configs (in Sekunden)

  widget:
    type: sonarr
    url: http://...
    key: ...
    cache: 60
  

• Disable Unused Widgets: Weniger ist mehr
• External Monitoring: Für Heavy-Metrics nutze Grafana-Embed statt Homepage-Widgets

Backup

Homepage-Config ist klein. Tägliches Backup:

#!/bin/bash
tar -czf homepage-backup-$(date +%Y%m%d).tar.gz -C /path/to/homepage .
# Upload zu NAS, S3, etc.

Oder als Cronjob im Container:

services:
  homepage:
    # ...
    volumes:
      - ./homepage:/app/config
      - ./backups:/backups
    entrypoint: /bin/sh -c "crond && node server.js"

Backups sollten API-Keys nicht im Klartext enthalten. Nutze verschlüsselte Backups (z.B. gpg, age) oder separates Secrets-Management (Vault, Bitwarden).

---

Reverse-Proxy und SSL

Homepage läuft per default auf HTTP Port 3000. Für Produktiv-Einsatz brauchst du SSL via Reverse-Proxy.

Nginx Proxy Manager

NPM ist die einfachste Lösung. Erstelle einen Proxy-Host:

• Domain: homepage.newsxc.net
• Scheme: http
• Forward Hostname: 192.168.60.100 (Homepage-Host)
• Forward Port: 3000
• SSL: Let’s Encrypt-Zertifikat
• Force SSL: Ja
• Websockets: Ja (für Live-Updates)

Traefik

Für Traefik-User via Docker-Labels:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.homepage.rule=Host(`homepage.newsxc.net`)"
      - "traefik.http.routers.homepage.entrypoints=websecure"
      - "traefik.http.routers.homepage.tls.certresolver=letsencrypt"
      - "traefik.http.services.homepage.loadbalancer.server.port=3000"

Authelia / Authentik

Homepage hat keine integrierte Auth. Für Multi-User-Szenarien nutze einen Auth-Proxy:

• Authelia: OIDC/LDAP-basierte Auth
• Authentik: Moderne SSO-Lösung
• OAuth2-Proxy: Simpler OAuth2-Proxy

Config-Beispiel für Authelia:

# In NPM: Access List mit Authelia-Integration
# Oder in Traefik: Middleware für Authelia

Für Homelab-internen Zugriff ist Auth optional. Für Internet-Exposition (via Cloudflare Tunnel, VPN) unbedingt Auth aktivieren.

---

Troubleshooting

Häufige Probleme und Lösungen:

Widget zeigt “API Error”

Ursachen:

• Falsche URL/Credentials
• API nicht erreichbar (Firewall, Network)
• Service unterstützt API nicht / API deaktiviert

Debug:

# Test API-Zugriff vom Homepage-Container
docker exec -it homepage curl http://sonarr:8989/api/v3/system/status?apikey=KEY

Lösung: Check URL, Key, Network-Connectivity. Viele Services haben API-Einstellungen, die aktiviert werden müssen.

Docker-Container werden nicht erkannt

Ursachen:

• Socket nicht gemountet
• Falsche docker.yaml-Config
• Labels fehlen

Debug:

# Check Socket-Mount
docker exec -it homepage ls -la /var/run/docker.sock

# Check Docker-API-Zugriff
docker exec -it homepage curl --unix-socket /var/run/docker.sock http://localhost/containers/json

Lösung: Stelle sicher, dass /var/run/docker.sock gemountet ist und docker.yaml korrekt konfiguriert ist.

Custom CSS wird nicht geladen

Ursachen:

• Datei nicht im richtigen Pfad
• Syntax-Fehler im CSS
• Browser-Cache

Lösung:

• CSS muss in /app/config/custom.css liegen (Volume-Path: ./homepage/custom.css)
• Check CSS-Syntax mit Validator
• Hard-Refresh im Browser (Ctrl+F5)

Performance-Probleme

Ursachen:

• Zu viele Widgets ohne Caching
• Langsame Service-APIs
• Ressourcen-Mangel (CPU/RAM)

Lösung:

• Aktiviere Widget-Caching
• Reduziere Widget-Anzahl
• Upgrade Homepage-Container-Ressourcen
• Check Service-API-Response-Times

YAML-Config-Fehler

Ursachen:

• Syntax-Fehler (Einrückung, Quotes)
• Ungültige Widget-Parameter

Debug:

# YAML-Validierung
docker logs homepage | grep -i error

# Online-YAML-Validator
cat services.yaml | pbcopy  # und paste in yamllint.com

Lösung: YAML ist Whitespace-sensitiv. Nutze 2 Spaces für Einrückung, keine Tabs. Achte auf korrekte Quotes bei Sonderzeichen.

Nutze einen Editor mit YAML-Support (VS Code + YAML-Extension, Neovim + yaml-language-server). Syntax-Highlighting und Validation sparen Zeit.

---

Advanced: Kubernetes-Integration

Homepage unterstützt Kubernetes-Cluster. Hier eine Kurzübersicht:

Installation via Helm

helm repo add jameswynn https://jameswynn.github.io/helm-charts
helm install homepage jameswynn/homepage

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: homepage
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  rules:
    - host: homepage.k8s.newsxc.net
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: homepage
                port:
                  number: 3000
  tls:
    - hosts:
        - homepage.k8s.newsxc.net
      secretName: homepage-tls

Service-Discovery

Homepage kann K8s-Services via API entdecken. Nutze Annotations ähnlich Docker-Labels:

apiVersion: v1
kind: Service
metadata:
  name: my-app
  annotations:
    homepage.group: "Applications"
    homepage.name: "My App"
    homepage.icon: "my-app.png"
    homepage.href: "https://my-app.k8s.newsxc.net"
    homepage.description: "My awesome app"
    homepage.widget.type: "kubernetes"
    homepage.widget.namespace: "default"
spec:
  selector:
    app: my-app
  ports:
    - port: 80

K8s-Integration ist fortgeschritten und braucht RBAC-Config. Für Homelab-Zwecke ist Docker-Integration meist ausreichend. K8s ist Overkill für <100 Services.

---

Fazit

Homepage ist das beste Dashboard für moderne Homelabs. Die Kombination aus über 100 Service-Widgets, Docker-Integration, YAML-Config und Performance macht es zur ersten Wahl. Egal ob du 5 oder 50 Services laufen hast: Homepage gibt dir den Überblick, den du brauchst.

Die wichtigsten Vorteile noch mal:

• Live-Monitoring: Echte API-Integration, nicht nur Bookmarks
• Docker-Native: Auto-Discovery via Labels spart Config-Zeit
• Git-Friendly: YAML-Configs perfekt für Versioning
• Performance: Next.js macht es blitzschnell
• Customizable: Themes, Custom CSS, Layouts nach Wunsch
• Community: Aktive Entwicklung, neue Widgets regelmäßig

Einziger Nachteil: Die initiale Config kann bei vielen Services aufwändig sein. Aber dank Docker-Labels und Git-Versionierung ist das einmalige Investment schnell amortisiert.

Wenn du dein Homelab-Dashboard upgraden willst: Homepage ist die Antwort. Probier es aus, du wirst nicht zurückwechseln.

Start small: Installiere Homepage, konfiguriere deine 5-10 wichtigsten Services. Erweitere iterativ. Nach einer Woche willst du’s nicht mehr missen.

---

Ressourcen

Offizielle Links

• Homepage GitHub: github.com/gethomepage/homepage
• Homepage Dokumentation: gethomepage.dev
• Widget-Liste: gethomepage.dev/widgets
• Docker Hub: ghcr.io/gethomepage/homepage

Icon-Ressourcen

• Dashboard Icons: github.com/walkxcode/dashboard-icons
• Material Design Icons: materialdesignicons.com
• Simple Icons: simpleicons.org

Community

• r/selfhosted: reddit.com/r/selfhosted
• Homepage Discord: Link im GitHub-Repo
• GitHub Discussions: Issues & Feature-Requests

Alternativen zum Vergleich

• Homarr: homarr.dev
• Dashy: dashy.to
• Heimdall: heimdall.site
• Organizr: organizr.app

Security-Tools

• Docker Socket Proxy: github.com/Tecnativa/docker-socket-proxy
• Authelia: authelia.com
• Authentik: goauthentik.io

Background Images

• Unsplash: Suche nach “server room”, “data center”, “circuit board”
• Pexels: Kostenlose High-Res-Bilder
• Wallhaven: Community-Wallpapers

Happy Dashboarding!