Dashy mit Docker installieren: Hochgradig anpassbares Homelab-Dashboard

Wer mehrere selbstgehostete Dienste betreibt, kennt das Problem: Bookmarks im Browser reichen irgendwann nicht mehr aus, und der Überblick über laufende Container geht verloren. Dashy löst das mit einem zentralen Homelab-Dashboard, das alle Dienste auf einer Seite versammelt, sie per HTTP-Ping auf Erreichbarkeit prüft und mit über 50 eingebauten Widgets (Wetter, RSS, Pi-Hole-Statistiken, Proxmox-Ressourcen, Krypto-Kurse und vieles mehr) anreichert. Dashy benötigt keine Datenbank, die gesamte Konfiguration steht in einer YAML-Datei. Diese Anleitung richtet sich an Administratoren, die Docker Compose kennen und Dashy auf einem Linux-Host, einer VM oder einem NAS betreiben möchten.

Voraussetzungen

• Linux-Host, VM oder NAS mit Docker Engine und Docker Compose v2 (Plugin oder Standalone). Falls noch nicht installiert: Docker und Docker Compose auf Linux installieren.
• Mindestens 256 MB freier RAM, 1 CPU-Kern, x86-64 oder ARM. Dashy 4.7.10 belegt im Leerlauf rund 50 MB RAM.
• Mindestens 1 GB freier Speicherplatz für das Docker-Image (rund 540 MB entpackt, Stand 4.7.10).
• Netzwerkzugriff auf den gewählten Host-Port (Standard: 4000) vom Browser aus.
• Optional: ein Reverse Proxy (Traefik, Nginx, Caddy) für HTTPS. Die Grundkonfiguration dazu ist in Traefik als Docker-Reverse-Proxy beschrieben.
• Texteditor (VS Code, Nano, Vim) für YAML-Dateien sowie curl zur CLI-Verifikation.

Schritt 1: Projektordner und Verzeichnisstruktur anlegen

Legen Sie einen eigenen Projektordner für Dashy an und erstellen Sie darin das Verzeichnis user-data, das später als Volume in den Container gemountet wird. Das Volume muss zwingend als Verzeichnis eingebunden werden, nicht als einzelne Datei, andernfalls schlägt das Laden von Sub-Konfigurationen, Icons und Custom-CSS fehl. Ältere Anleitungen im Netz zeigen noch den veralteten Pfad /app/public/conf.yml. Der korrekte Pfad seit Version 3.x lautet /app/user-data.

$ mkdir -p /opt/dashy/user-data
$ cd /opt/dashy

Setzen Sie die Eigentümerschaft auf UID 1000, unter der Dashy im Container läuft. Gehört das Verzeichnis einem anderen Benutzer, kommt es beim Speichern der Konfiguration zu einem EACCES-Fehler:

$ sudo chown -R 1000:1000 /opt/dashy/user-data

$ ls -la /opt/dashy/

# Erwartete Ausgabe (Auszug):
# drwxr-xr-x  2 1000 1000 4096 Jun 11 10:00 user-data

Schritt 2: .env-Datei anlegen

Alle umgebungsabhängigen Werte gehören in eine .env-Datei, damit compose.yaml portabel bleibt. Dashy benötigt keine Datenbank-Passwörter oder API-Secrets als Pflichtparameter. Der wichtigste Wert ist der externe Host-Port. Der Container läuft fest mit UID 1000, deshalb gehört user-data diesem Benutzer (Schritt 1).

# /opt/dashy/.env

# Externer Host-Port für die Dashy Web-UI (interner Container-Port ist immer 8080)
DASHY_PORT=4000

$ ls -la /opt/dashy/.env

# -rw-r--r-- 1 root root ... .env

Schritt 3: compose.yaml erstellen

Erstellen Sie die compose.yaml im Projektordner. Das Image lissy93/dashy:latest ist ein Multi-Arch-Manifest und unterstützt amd64, arm64 und arm/v7 (kein separates Tag für Raspberry Pi oder andere ARM-Geräte nötig). Für reproduzierbare Updates schreiben Sie eine feste Version fest, etwa :4.9.0 (Stand Oktober 2026). Als Alternative bei Docker-Hub-Rate-Limits steht ghcr.io/lissy93/dashy:latest bereit.

# /opt/dashy/compose.yaml

services:
  dashy:
    container_name: dashy
    image: lissy93/dashy:latest
    ports:
      - "${DASHY_PORT:-4000}:8080"
    volumes:
      - ./user-data:/app/user-data
    environment:
      - NODE_ENV=production
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'node', '/app/services/healthcheck.js']
      interval: 1m30s
      timeout: 10s
      retries: 3
      start_period: 30s

$ docker compose config

# Erwartete Ausgabe: die geparste compose.yaml ohne Fehlermeldung

Schritt 4: Container starten

Starten Sie Dashy im Hintergrund. Beim ersten Start lädt Docker das Image. Einen Frontend-Build zur Laufzeit gibt es seit Version 4 nicht mehr, der Server steht nach wenigen Sekunden. Liegt in user-data noch keine conf.yml, meldet das Log Config file could not be found. Legen Sie die Datei dann wie in Schritt 5 an.

$ cd /opt/dashy
$ docker compose up -d

Den Start live verfolgen:

$ docker compose logs -f dashy

Das Dashboard ist startklar, sobald in den Logs Your new dashboard is now up and running erscheint.

$ docker compose ps

# NAME    IMAGE                    COMMAND   SERVICE   STATUS          PORTS
# dashy   lissy93/dashy:latest     ...       dashy     Up (healthy)    0.0.0.0:4000->8080/tcp

$ curl -I http://localhost:4000

# HTTP/1.1 200 OK

Solange der Healthcheck noch im start_period liegt, zeigt docker compose ps den Status Up (health: starting). Das ist normal und kein Fehler. Nach unter einer Minute wechselt er zu Up (healthy).

Schritt 5: Erste Konfiguration im Browser

Öffnen Sie http://<HOST-IP>:4000 im Browser. Ohne eigene conf.yml zeigt Dashy eine Standardansicht. Es gibt zwei Wege, das Dashboard anzupassen:

1. Visueller UI-Editor: Klicken Sie auf das Zahnrad-Symbol oben rechts, dann auf „Edit“. Hier lassen sich Abschnitte, Links und Widgets per Formular hinzufügen, ohne YAML anfassen zu müssen. Änderungen werden direkt in ./user-data/conf.yml geschrieben.
2. Direkte YAML-Bearbeitung: Bearbeiten Sie /opt/dashy/user-data/conf.yml mit einem Texteditor und laden Sie die Seite neu. Validieren Sie die Datei vorher unter yamllint.com, da ein YAML-Syntaxfehler zu einer leeren Dashboard-Ansicht führt.

Eine minimale conf.yml mit zwei Dienst-Links und aktiviertem Status-Check sieht so aus:

# /opt/dashy/user-data/conf.yml

appConfig:
  theme: colorful
  statusCheckInterval: 30
  enableFontAwesome: true

pageInfo:
  title: Mein Homelab

sections:
  - name: Infrastruktur
    items:
      - title: Portainer
        url: http://192.168.1.10:9000
        icon: fab fa-docker
        statusCheck: true
      - title: Proxmox
        url: https://192.168.1.20:8006
        icon: fas fa-server
        statusCheck: true
        statusCheckUrl: https://192.168.1.20:8006/api2/json/version
        statusCheckAllowInsecure: true

Verwenden Sie für lokale Dienste nie localhost oder 127.0.0.1. Aus dem Container heraus ist damit der Container selbst gemeint, nicht der Host. Nutzen Sie stattdessen die LAN-IP des Hosts (zum Beispiel 192.168.1.10) oder host.docker.internal (nur Docker Desktop).

Schritt 6: Widgets einrichten

Dashy bietet über 50 eingebaute Widgets, die direkt in conf.yml unter einem widgets-Schlüssel in einem Abschnitt konfiguriert werden. Hier ein Beispiel mit einem Wetter-Widget und einem Pi-Hole-Widget:

sections:
  - name: Übersicht
    widgets:
      - type: weather
        options:
          apiKey: IHR_OPENWEATHERMAP_KEY
          city: Berlin
          units: metric
          lang: de
      - type: pi-hole-stats
        options:
          hostname: http://192.168.1.5
          hideStatus: false

API-Keys für Widgets können statt direkt in conf.yml auch als Umgebungsvariablen im Container gesetzt werden. Das ist sicherer, weil die Keys dann nicht in der Konfigurationsdatei landen. Dazu die Variable in .env eintragen und unter environment in compose.yaml referenzieren.

Schritt 7: Authentifizierung einrichten (optional)

Ohne Authentifizierung ist das Dashboard öffentlich zugänglich, für ein rein lokales Heimnetz oft ausreichend. Für den Zugriff über das Internet ist ein Passwortschutz Pflicht. Dashy bietet eine eingebaute Nutzerverwaltung über appConfig.auth:

appConfig:
  auth:
    enableGuestAccess: false
    users:
      - name: admin
        credentials: SHA256_HASH_DES_PASSWORTS
        type: admin

Den SHA-256-Hash des gewünschten Passworts erzeugen:

$ echo -n "MeinPasswort123" | sha256sum

# Ausgabe: a1b2c3d4...  (Hash kopieren und als credentials eintragen)

Schritt 8: Updates und Backup

Dashy aktualisieren:

$ cd /opt/dashy
$ docker compose pull
$ docker compose up -d

Version 4.8.0 bringt Kurznamen (Aliase) für den Schnellstart von Einträgen, ein neu gebautes Pi-hole-Widget für die API von Pi-hole v6 sowie vervollständigte deutsche Übersetzungen. Das Update einer 4.7.10-Instanz mit eigener conf.yml auf 4.8.0 läuft ohne Eingriff: Der Container ist nach rund einer Minute wieder healthy, das Log meldet Using Dashy V-4.8.0, und die Konfiguration bleibt erhalten.

Version 4.9.0 bringt laut Release Notes eine neue Workspace-Ansicht, ein Theme liquid-glass und behebt eine Lücke, über die Konfigurationsdateien per kodierter URL ohne Anmeldung lesbar waren. Neue Pflichtvariablen gibt es nicht. Beim Update von 4.8.0 auf 4.9.0 mit dieser Compose-Datei ist der Container nach wenigen Sekunden healthy, das Log meldet Config file is valid, no issues found und Using Dashy V-4.9.0, und die eigene conf.yml bleibt erhalten. Beachten Sie: Mit der eingebauten Anmeldung aus Schritt 7 liefert /conf.yml weiter HTTP 200 ohne Anmeldung, denn diese Anmeldung prüft nur der Browser. Zugangsdaten und interne Adressen in der conf.yml schützt erst ein vorgeschalteter Reverse Proxy mit Anmeldung.

Das einzige Backup-relevante Verzeichnis ist ./user-data. Es enthält conf.yml, benutzerdefinierte Icons, Fonts und CSS. Eine einfache Sicherung:

$ tar -czf dashy-backup-$(date +%Y%m%d).tar.gz /opt/dashy/user-data/

Für eine durchdachte automatische Backup-Strategie: 3-2-1-Backup-Strategie umsetzen mit Restic.

$ docker compose ps

# NAME    IMAGE                    COMMAND   SERVICE   STATUS          PORTS
# dashy   lissy93/dashy:latest     ...       dashy     Up (healthy)    0.0.0.0:4000->8080/tcp

$ docker compose logs --tail=20 dashy

# Keine Fehlerzeilen; letzte Zeile zeigt Server-Start

Grundlagen zum Betrieb finden Sie in Docker Compose absichern: Secrets, Healthchecks, Non-Root.

Troubleshooting / Typische Fehler

Error, unable to find config oder leeres Dashboard

Das Volume wurde als einzelne Datei statt als Verzeichnis gemountet (zum Beispiel -v ~/conf.yml:/app/user-data/conf.yml). Fix: Volume auf ./user-data:/app/user-data (Verzeichnis) ändern und Container neu erstellen.

EACCES oder EROFS beim Speichern der Konfiguration

Das Host-Verzeichnis gehört nicht UID 1000. Fix: sudo chown -R 1000:1000 ./user-data ausführen und Container neu starten.

Heap Limit Allocation Failed oder SIGKILL beim ersten Start

Betrifft Dashy 2.x und 3.x, die das Frontend beim Start bauten. Fix: auf Version 4 aktualisieren oder dem Container mindestens 2 GB RAM zuweisen.

HTTP 429 beim Image-Pull

Docker-Hub-Rate-Limit erreicht. Fix: ghcr.io/lissy93/dashy:latest als Image-Quelle verwenden oder docker login ausführen.

Error, unable to validate conf.yml

YAML-Syntaxfehler (falsche Einrückung, fehlendes Leerzeichen). Fix: Datei unter yamllint.com validieren, Fehler beheben, Browser neu laden.

Widgets oder Status-Checks erreichen lokale Dienste nicht

localhost oder 127.0.0.1 als Zieladresse verwendet. Fix: LAN-IP des Hosts (zum Beispiel 192.168.1.10) oder host.docker.internal (Docker Desktop) verwenden.

Konfigurationsänderungen nicht sichtbar

Browser-Local-Storage cached die alte Konfiguration. Fix: Seite im Inkognito-Modus öffnen oder über das Dashy-Menü den Cache leeren.

Font-Awesome-Icons fehlen

Standard ist enableFontAwesome: false. Fix: enableFontAwesome: true unter appConfig in conf.yml setzen.

SELinux blockiert Schreibzugriff (Fedora, RHEL)

Das Speichern der Konfiguration schlägt still fehl. Fix: Volume-Mount mit :Z-Flag versehen: ./user-data:/app/user-data:Z.

Häufige Fragen

Braucht Dashy eine Datenbank (PostgreSQL, MySQL, Redis)?

Nein. Dashy ist vollständig datenbanklos. Die gesamte Konfiguration liegt in einer einzigen Datei: ./user-data/conf.yml. Es gibt keine externe Datenbankabhängigkeit. Das ist einer der Hauptgründe, warum der Betrieb so unkompliziert ist.

Wie ändere ich die Konfiguration nach dem ersten Start?

Entweder direkt die Datei ./user-data/conf.yml auf dem Host bearbeiten und danach den Browser-Cache leeren, oder den eingebauten visuellen UI-Editor im Browser unter dem Zahnrad-Symbol nutzen. Änderungen über den UI-Editor werden sofort in conf.yml geschrieben, sofern Schreibrechte korrekt gesetzt sind. Ein Containerneustart ist für Konfigurationsänderungen nicht erforderlich.

Läuft Dashy auf dem Raspberry Pi?

Ja. Das :latest-Image ist ein Multi-Arch-Manifest und unterstützt nativ amd64, arm64 und arm/v7. Kein separates Image oder Tag nötig: docker compose up -d funktioniert direkt auf allen unterstützten Architekturen. Seit Version 4 genügt auch ein Raspberry Pi mit 1 GB RAM, weil der Frontend-Build zur Laufzeit entfällt.

Wie richte ich Status-Checks für meine Dienste ein?

In conf.yml unter items das Flag statusCheck: true setzen. Dann wird die url des Links als Ping-Endpunkt genutzt. Mit statusCheckUrl lässt sich eine abweichende URL prüfen (zum Beispiel ein Health-Endpoint statt der UI-URL). Das globale Prüfintervall steuert statusCheckInterval (Sekunden) unter appConfig.

Kann Dashy hinter einem Reverse Proxy laufen?

Ja, problemlos. Den externen Port auf 80/443 leiten und Dashy intern auf Port 8080 lassen. Wenn Dashy unter einem Sub-Pfad erreichbar sein soll (zum Beispiel /dashy), die Umgebungsvariable BASE_URL=/dashy in compose.yaml ergänzen, ohne abschließenden Slash.

Wie sichere ich Dashy mit einem Passwort ab?

Unter appConfig.auth.users einen Nutzer mit name, credentials (SHA-256-Hash des Passworts) und type (admin oder viewer) anlegen. Den Hash erzeugt echo -n "Passwort" | sha256sum. Für produktive Umgebungen empfiehlt sich zusätzlich ein vorgelagerter Reverse Proxy mit Header-Auth oder Keycloak/OIDC, da die eingebaute Authentifizierung client-seitig arbeitet.

Fazit

Dashy eignet sich, wenn Sie Ihre selbstgehosteten Dienste unter einer einheitlichen Oberfläche vereinen wollen. Die datenbanklose Architektur und der UI-Editor erleichtern den Einstieg, Theme-System, mehrere Seiten und Authentifizierung reichen auch für größere Setups. Seit Version 4 ist Dashy sparsam genug für kleine Heimserver. Beachten Sie, dass die eingebaute Anmeldung nur clientseitig schützt. Wer ergänzend zur Dashboard-Übersicht tiefergehende Metriken seiner Container sammeln möchte, findet mit Beszel Server Monitoring mit Docker eine passende Ergänzung.

Weiterführende Anleitungen und Quellen

1. Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage
2. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten
3. Beszel Server Monitoring mit Docker einrichten
4. 3-2-1-Backup-Strategie umsetzen mit Restic

Offizielle Quellen: Dashy GitHub Repository | Dashy Deployment-Dokumentation | Dashy Widget-Dokumentation