Homarr mit Docker installieren: Modernes Homelab-Dashboard mit Drag-and-Drop und 40+ Integrationen

Wer mehrere Self-Hosted-Dienste betreibt, kennt das Problem: Browser-Tabs für Sonarr, Radarr, Jellyfin, Plex, Pi-hole und ein Dutzend weiterer Apps stapeln sich, und der Überblick fehlt. Homarr löst genau dieses Problem – als modernes, browserbasiertes Homelab-Dashboard, das alle deine Self-Hosted-Apps auf einer einzigen, übersichtlichen Seite zusammenführt. Das Besondere: Die gesamte Konfiguration läuft per Drag-and-Drop im Browser, kein einziges YAML muss angefasst werden. Dazu kommen über 40 native Integrationen, die echte Daten aus deinen Apps ziehen – etwa neue Episoden in Sonarr oder aktuelle Download-Queues in qBittorrent –, sowie ein eingebautes Benutzer- und Berechtigungssystem mit OIDC- und LDAP-Unterstützung. Wer bisher auf Homepage oder einen anderen Dashboard-Ansatz gesetzt hat, findet in Homarr eine deutlich interaktivere Alternative. Diese Anleitung führt dich durch die vollständige Docker-Compose-Installation auf einem generischen Linux-Host (Ubuntu, Debian, NAS mit Docker), erklärt alle wichtigen Stellschrauben und zeigt nach jedem Schritt, wie du den Fortschritt verifizierst.

Voraussetzungen

1. Docker Engine >= 20.x und Docker Compose Plugin v2 auf dem Host installiert – falls noch nicht vorhanden, hilft die Anleitung Docker und Docker Compose auf Linux installieren.
2. Linux-Host, VM oder NAS mit Docker-Unterstützung (x86_64 oder arm64 – läuft auch auf dem Raspberry Pi).
3. Mindestens 512 MB freier RAM (empfohlen: 1 GB+), mindestens 500 MB freier Speicherplatz für Image und Appdata.
4. Internetverbindung beim ersten Start, damit Docker das Image von ghcr.io pullen kann.
5. openssl auf dem Host verfügbar (für die Schlüsselgenerierung – auf allen gängigen Linux-Distributionen vorinstalliert).
6. Netzwerkzugang zu Port 7575 des Hosts vom Browser aus.
7. Optional, aber empfohlen: ein Reverse Proxy für HTTPS (Nginx Proxy Manager, Traefik oder Caddy) – Homarr selbst bietet kein TLS.

Schritt 1: Projektordner anlegen

Alle Dateien eines Docker-Compose-Projekts gehören in einen eigenen Ordner. Wähle einen Ort, der dir passt – /opt/homarr für systemweite Dienste oder ~/homarr im Home-Verzeichnis sind beides übliche Konventionen.

mkdir -p /opt/homarr
cd /opt/homarr

Das Unterverzeichnis für die persistenten Anwendungsdaten legt Homarr beim ersten Start selbst an. Du musst es nicht manuell erstellen – wichtig ist nur, dass der Projektordner existiert und der Benutzer, der Docker ausführt, Schreibrechte hat.

Verifizieren: ls -la /opt/homarr zeigt den leeren Ordner ohne Fehler. Wenn du PUID/PGID (z. B. 1000) nutzen möchtest, setze jetzt die Berechtigungen: mkdir -p /opt/homarr/homarr/appdata && chown -R 1000:1000 /opt/homarr/homarr/appdata.

Schritt 2: SECRET_ENCRYPTION_KEY generieren und .env anlegen

Der SECRET_ENCRYPTION_KEY ist die einzige Pflicht-Umgebungsvariable von Homarr. Er wird für AES-256-CBC-Verschlüsselung aller Integrations-Credentials in der SQLite-Datenbank verwendet. Ohne diesen Schlüssel verweigert der Container den Start. Erzeuge ihn einmalig mit:

openssl rand -hex 32

Das ergibt einen 64-stelligen Hex-String, zum Beispiel a3f8c2…. Speichere diesen Wert jetzt sofort an einem sicheren Ort (Passwortmanager). Lege dann die .env-Datei an:

# /opt/homarr/.env
# PFLICHT: 64-stelliger Hex-String (openssl rand -hex 32)
# WARNUNG: Diesen Wert NIEMALS nachtraglich aendern!
# Alle gespeicherten Integrations-Credentials werden mit diesem Key
# verschlüsselt. Ein Wechsel macht alle Daten unlesbar.
SECRET_ENCRYPTION_KEY=hier_deinen_generierten_hex_string_eintragen

Sichere die Datei mit restriktiven Rechten, damit andere Benutzer den Schlüssel nicht lesen können:

chmod 600 /opt/homarr/.env

Verifizieren: wc -c <<< "$SECRET_ENCRYPTION_KEY" nach einem source /opt/homarr/.env sollte 65 zeigen (64 Zeichen + Newline). Alternativ: grep SECRET_ENCRYPTION_KEY /opt/homarr/.env | awk -F= '{print length($2)}' muss 64 liefern. Wenn der Wert kürzer ist, funktioniert Homarr nicht.

Schritt 3: compose.yaml anlegen

Lege die Compose-Datei im Projektordner an. Das Image kommt ausschließlich von der GitHub Container Registry (ghcr.io/homarr-labs/homarr) – ältere Anleitungen zeigen noch ghcr.io/ajnart/homarr oder linuxserver/homarr, beide sind seit dem Rewrite auf v1.0 veraltet und werden nicht mehr gepflegt.

# /opt/homarr/compose.yaml
services:
  homarr:
    container_name: homarr
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    ports:
      - "7575:7575"
    volumes:
      # Pflicht: persistente Anwendungsdaten (SQLite-DB, Konfiguration, Logs)
      - ./homarr/appdata:/appdata
      # Optional: Docker-Socket für Container-Integration (Starten/Stoppen,
      # Logs, Stats-Widget). Gewaehrt vollständige Docker-Kontrolle!
      # Sicherere Alternative: Tecnativa/docker-socket-proxy vorschalten.
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      # Pflicht: aus .env-Datei lesen
      - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
      # Optional: Nicht-Root-Betrieb (Rechte auf appdata-Ordner vorher setzen!)
      # - PUID=1000
      # - PGID=1000
      # Optional: Log-Level (debug, info, warn, error) - Standard: info
      # - LOG_LEVEL=info
      # Optional: DNS-Caching deaktivieren bei Netzwerkproblemen
      # - ENABLE_DNS_CACHING=false
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:7575"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

Ein paar Punkte zur compose.yaml, die Fragen ersparen:

1. Docker-Socket: Der Mount /var/run/docker.sock:/var/run/docker.sock ist optional. Ohne ihn läuft Homarr als reines Link-Dashboard ohne Container-Steuerung. Mit ihm kannst du Container direkt aus dem Dashboard starten, stoppen und Logs lesen – aber der Container erhält damit faktisch root-Zugriff auf den Docker-Daemon. Für Produktivumgebungen empfiehlt die offizielle Dokumentation einen Socket Proxy.
2. SQLite läuft intern: Du brauchst keinen separaten Datenbank-Container. Die SQLite-Datenbank liegt unter ./homarr/appdata/db/db.sqlite und wächst mit deiner Konfiguration.
3. Redis läuft intern: Ebenfalls kein separater Redis-Container nötig. Externer Redis ist nur für Multi-Instanz- oder Kubernetes-Deployments relevant.

Verifizieren: docker compose -f /opt/homarr/compose.yaml config zeigt die aufgelöste Konfiguration ohne Fehler. Wenn der SECRET_ENCRYPTION_KEY aus der .env korrekt gelesen wird, erscheint er (zensiert) in der Ausgabe unter environment.

Schritt 4: Container starten

Wechsle in den Projektordner und starte Homarr im Hintergrund:

cd /opt/homarr
docker compose up -d

Docker pullt das Image von ghcr.io (ca. 200–400 MB je nach Architektur) und startet den Container. Beim ersten Start initialisiert Homarr die SQLite-Datenbank und den internen Redis – das kann 20–30 Sekunden dauern.

Prüfe den Container-Status und die Logs:

# Container-Status und Health-Check
docker compose ps

# Live-Logs verfolgen (Ctrl+C zum Beenden)
docker compose logs -f homarr

Erwartete Ausgabe von docker compose ps nach dem Start:

NAME      IMAGE                              COMMAND   SERVICE   CREATED         STATUS                   PORTS
homarr    ghcr.io/homarr-labs/homarr:latest  ...       homarr    2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:7575->7575/tcp

In den Logs sollte keine Zeile mit ERROR oder FATAL erscheinen. Eine Erfolgsmeldung wie Server running on http://0.0.0.0:7575 oder ähnlich zeigt an, dass der Container bereit ist.

Verifizieren: curl -s -o /dev/null -w "%{http_code}" http://localhost:7575 gibt 200 oder 302 zurück. Falls der Container nicht startet und die Logs SECRET_ENCRYPTION_KEY is required zeigen, prüfe, ob die .env-Datei im selben Verzeichnis wie die compose.yaml liegt und der Schlüssel genau 64 Hex-Zeichen hat.

Schritt 5: Ersteinrichtung im Browser

Öffne http://<HOST-IP>:7575 im Browser. Beim ersten Aufruf führt dich Homarr durch einen Einrichtungsassistenten:

1. Admin-Account anlegen: Benutzername, E-Mail-Adresse und Passwort für den ersten Administrator festlegen. Dieser Account hat vollen Zugriff auf alle Einstellungen.
2. Dashboard-Name: Einen Namen für dein Dashboard vergeben (erscheint im Browser-Tab und als Seitentitel).
3. Erste App hinzufügen (optional): Du kannst direkt mit dem Hinzufügen der ersten App beginnen oder den Assistenten überspringen und später über „Apps" im Einstellungsmenü arbeiten.

Danach landest du im leeren Dashboard. Über das Bearbeiten-Symbol (Stift oben rechts) aktivierst du den Bearbeitungsmodus, in dem du Widgets per Drag-and-Drop platzieren und skalieren kannst. Integrationen – also die Verbindungen zu Sonarr, Radarr, Jellyfin und Co. – richtest du unter Einstellungen → Integrationen ein. Dort trägst du die jeweilige URL und den API-Key deiner App ein; Homarr zieht dann live Daten für die entsprechenden Widgets.

Verifizieren: Du siehst die Homarr-Web-UI im Browser und kannst dich mit dem soeben angelegten Admin-Account anmelden. Unter Einstellungen → Über Homarr wird die aktuelle Version angezeigt (sollte v1.65.0 oder neuer sein).

Schritt 6: Docker-Socket-Integration einrichten (optional)

Wenn du den Docker-Socket gemountet hast, kannst du in Homarr unter Einstellungen → Integrationen → Docker den lokalen Docker-Daemon als Integration hinzufügen. Danach stehen dir das Container-Widget (zeigt laufende Container mit CPU- und RAM-Verbrauch) sowie die Möglichkeit zur Verfügung, Container direkt aus dem Dashboard zu starten und zu stoppen.

Für sensiblere Umgebungen empfiehlt sich stattdessen der Einsatz eines Socket Proxys. Die Anleitung Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only erklärt, wie du Sicherheitsrisiken durch Socket-Mounts minimierst.

Verifizieren: Unter Einstellungen → Integrationen erscheint „Docker" mit grünem Status-Indikator, wenn die Verbindung erfolgreich ist. Ein gelber oder roter Indikator deutet auf ein Berechtigungsproblem hin – meist fehlt dem Container-Benutzer der Zugriff auf den Socket (siehe Troubleshooting).

Schritt 7: HTTPS mit Reverse Proxy einrichten (empfohlen)

Homarr stellt selbst kein HTTPS bereit. Für den Zugriff über das Internet oder für Authentifizierung per OIDC ist HTTPS zwingend erforderlich. Schalte einen Reverse Proxy vor, der TLS terminiert und Anfragen an Port 7575 weiterleitet.

Drei bewährte Optionen im Homelab:

Wichtig: Wenn Homarr hinter einem Reverse Proxy läuft und OIDC-Authentifizierung (z. B. Authentik oder Keycloak) verwendet werden soll, muss der Proxy die korrekten X-Forwarded-For- und X-Forwarded-Proto-Header setzen, damit Homarr die HTTPS-Weiterleitungen korrekt berechnet.

Verifizieren: curl -I https://homarr.deine-domain.de gibt HTTP/2 200 zurück (oder eine Weiterleitung auf die Login-Seite, falls Authentifizierung aktiv ist). Das Zertifikat ist gültig und vom Browser akzeptiert.

Schritt 8: Update und Backup

Homarr wird aktiv gepflegt (zuletzt v1.65.0, Apache-2.0-Lizenz). Ein Update läuft über die üblichen Docker-Compose-Befehle:

cd /opt/homarr
docker compose pull
docker compose up -d
# Altes Image aufräumen
docker image prune -f

Für automatische Updates kannst du Watchtower einsetzen – beachte dabei, dass der SECRET_ENCRYPTION_KEY in der .env-Datei erhalten bleiben muss. Ein Update verändert den Key niemals automatisch; er kann sich nur ändern, wenn du die .env manuell bearbeitest.

Das vollständige Backup von Homarr beschränkt sich auf zwei Dinge:

1. Die Datei /opt/homarr/.env (enthält den SECRET_ENCRYPTION_KEY – das wichtigste Backup überhaupt).
2. Das Verzeichnis /opt/homarr/homarr/appdata/ (enthält SQLite-Datenbank, Konfiguration, Logs und Icon-Cache).

Für eine vollständige Wiederherstellung auf einem neuen Host reicht es, beide Punkte in denselben relativen Pfaden bereitzustellen und docker compose up -d auszuführen.

Verifizieren: Nach dem Update zeigt docker compose ps den Container als (healthy) und unter Einstellungen → Über Homarr ist die neue Versionsnummer sichtbar. Die gesamte Dashboard-Konfiguration ist erhalten, da das Volume nicht verändert wurde.

Troubleshooting / Typische Fehler

1. Container startet nicht, Logs zeigen „SECRET_ENCRYPTION_KEY is required" oder ähnlich: Die Umgebungsvariable fehlt oder ist leer. Prüfe, ob die .env-Datei im selben Verzeichnis wie die compose.yaml liegt (ls -la /opt/homarr/.env) und ob der Wert genau 64 Hex-Zeichen hat. Kein Leerzeichen, kein Zeilenumbruch im Wert.
2. Alle Integrations-Credentials verloren nach Container-Neuaufbau: Der SECRET_ENCRYPTION_KEY wurde neu generiert. Dieser Schlüssel muss für die gesamte Lebenszeit der Instanz gleich bleiben. Alle verschlüsselten Daten in der Datenbank sind untrennbar mit dem ursprünglichen Key verbunden. Backup der .env-Datei ist Pflicht.
3. Datenverlust nach Container-Neustart – Konfiguration und Datenbank verschwunden: Das Volume ./homarr/appdata:/appdata ist nicht korrekt gemountet. Prüfe den relativen Pfad: Dieser bezieht sich auf das Verzeichnis, in dem docker compose aufgerufen wird – also /opt/homarr/homarr/appdata. Mit docker compose exec homarr ls /appdata kannst du prüfen, ob das Volume korrekt verbunden ist.
4. Docker-Socket-Fehler „permission denied": Der Container-Prozess (PUID/PGID) hat keinen Zugriff auf /var/run/docker.sock. Lösung A: PUID/PGID-Variablen aus der compose.yaml entfernen (Container läuft dann als root). Lösung B: Den Host-Benutzer zur docker-Gruppe hinzufügen: usermod -aG docker dein-benutzer, dann ausloggen und neu anmelden. Lösung C: Socket Proxy vorschalten.
5. Volume-Berechtigungsfehler beim Start mit PUID=1000: Das Host-Verzeichnis gehört root, der Container-Prozess läuft als UID 1000. Fix: chown -R 1000:1000 /opt/homarr/homarr/appdata auf dem Host ausführen, bevor der Container startet.
6. Integrationen liefern keine Daten, Verbindung schlägt fehl: Homarr läuft im Standard-Bridge-Netzwerk und kann andere Container nicht über deren Container-Namen erreichen. Lösung: Alle betreffenden Container in dasselbe Docker-Netzwerk einbinden oder statt Container-Namen die Host-IP verwenden. Mit docker network ls und docker network inspect kannst du die Netzwerktopologie prüfen.
7. „Internal Server Error" für bestimmte Integrationen: In manchen Netzwerkkonfigurationen verursacht das standardmäßig aktivierte DNS-Caching Probleme (GitHub Issue #4006). Setze ENABLE_DNS_CACHING=false in der .env und starte den Container neu.
8. Altes Image (ajnart/homarr oder linuxserver/homarr) – Migration zu v1.x: Homarr v1.0 war ein vollständiger Rewrite; v0.x-Konfigurationen sind nicht kompatibel. Beide Container können parallel laufen (anderer Port), die Konfiguration muss im neuen Interface manuell neu angelegt werden.

Häufige Fragen

Brauche ich eine externe Datenbank (PostgreSQL) oder Redis?

Nein – für eine Einzelinstanz-Installation nicht. SQLite läuft ohne externe Konfiguration direkt im Container unter /appdata/db/db.sqlite. Redis läuft ebenfalls intern. PostgreSQL und externer Redis sind nur für Multi-Instanz-, Hochverfügbarkeits- oder Kubernetes-Deployments nötig, bei denen mehrere Homarr-Instanzen dieselbe Datenbank teilen müssen.

Wie setze ich den SECRET_ENCRYPTION_KEY sicher?

Generiere ihn einmalig mit openssl rand -hex 32 und trage ihn in der .env-Datei ein. Referenziere ihn in der compose.yaml mit ${SECRET_ENCRYPTION_KEY}. Sichere die .env-Datei sofort in einem Passwortmanager oder verschlüsselten Backup. Dieser Wert darf nach dem ersten Start nie mehr geändert werden.

Ist HTTPS möglich, und wie richte ich es ein?

Homarr stellt selbst kein HTTPS bereit. HTTPS wird über einen vorgelagerten Reverse Proxy realisiert: Nginx Proxy Manager, Traefik oder Caddy terminieren TLS nach außen und leiten Anfragen intern an Port 7575 weiter. Homarr selbst bleibt auf HTTP. Für OIDC-Authentifizierung ist HTTPS zwingend erforderlich.

Kann Homarr meine laufenden Docker-Container anzeigen und steuern?

Ja, wenn du den Docker-Socket als Volume mountest (/var/run/docker.sock:/var/run/docker.sock). Dann kannst du unter Einstellungen → Integrationen → Docker den lokalen Daemon verbinden und erhältst ein Container-Widget mit Live-Stats sowie die Möglichkeit, Container zu starten und zu stoppen. Aus Sicherheitsgründen empfiehlt die offizielle Dokumentation den Einsatz eines Socket Proxys statt direktem Socket-Mount.

Wie aktualisiere ich Homarr auf die neueste Version?

Mit drei Befehlen: docker compose pull, dann docker compose up -d, dann docker image prune -f. Die Konfiguration im appdata-Volume bleibt vollständig erhalten. Für automatische Updates eignet sich Watchtower; stelle dabei sicher, dass die .env-Datei mit dem SECRET_ENCRYPTION_KEY jederzeit gesichert ist.

Wie unterscheidet sich Homarr von Homepage oder Glance?

Homepage und Glance sind YAML-basiert: die gesamte Konfiguration erfolgt über Konfigurationsdateien. Homarr dagegen ist ein No-Code-Dashboard – alle Einstellungen (Widgets, Apps, Layout) werden per Drag-and-Drop im Browser vorgenommen, ohne eine einzige Zeile YAML zu schreiben. Dafür bringt Homarr ein deutlich umfangreicheres Widget-System mit nativen Integrationen und ein eingebautes Authentifizierungssystem mit. Wer YAML bevorzugt oder minimale Ressourcen benötigt, ist mit Homepage oder Glance gut beraten; wer eine interaktive, klickbare Konsole will, greift zu Homarr.

Was passiert bei einer vollständigen Deinstallation?

Container stoppen und entfernen: docker compose down. Anschließend das Projektverzeichnis löschen: rm -rf /opt/homarr. Das Image entfernen: docker image rm ghcr.io/homarr-labs/homarr:latest oder docker image prune. Damit ist Homarr vollständig vom System entfernt.

Fazit

Homarr ist die konsequenteste Antwort auf die Frage, wie ein modernes Homelab-Dashboard aussehen soll: kein YAML, kein Neustart für jede Konfigurationsänderung, stattdessen Drag-and-Drop und live aktualisierte Widgets. Die über 40 nativen Integrationen – von Sonarr und Radarr über Jellyfin bis hin zu Docker selbst – machen es zu mehr als einer einfachen Linksammlung. Besonders praktisch ist das eingebaute Authentifizierungssystem mit OIDC- und LDAP-Unterstützung, das einen separaten Auth-Proxy überflüssig macht. Der einzige Haken, den du im Hinterkopf behalten musst: der SECRET_ENCRYPTION_KEY ist unveränderlich – wer ihn verliert oder versehentlich ändert, verliert alle gespeicherten Integrations-Credentials. Ein Backup der .env-Datei ist deshalb genauso wichtig wie das Backup des Appdata-Verzeichnisses. Wenn du außerdem Docker-Images regelmäßig auf bekannte Schwachstellen prüfen möchtest, lohnt sich ein Blick auf die Anleitung Docker-Images auf Schwachstellen scannen mit Trivy.

Weiterführende Anleitungen und Quellen

1. Docker und Docker Compose auf Linux installieren (Ubuntu/Debian) – Grundlage für alle Docker-Projekte
2. Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only – Socket-Proxy und weitere Sicherheitsmaßnahmen
3. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS – HTTPS für Homarr und alle anderen Self-Hosted-Apps
4. Watchtower mit Docker: Container automatisch aktualisieren – automatische Homarr-Updates
5. Docker-Images auf Schwachstellen scannen mit Trivy
6. Beszel Server Monitoring mit Docker einrichten – Ergänzung zu Homarr für tiefes Server-Monitoring

Offizielle Quellen: Homarr Dokumentation – Docker-Installation | Homarr Dokumentation – Umgebungsvariablen | GitHub: homarr-labs/homarr

Passende Anleitungen auf S-EDV

1. OpenSSL: Neun Schwachstellen im Sicherheitsrelease vom 9. Juni 2026, darunter Hi
2. Automatische Sicherheitsupdates unter Debian/Ubuntu mit unattended-upgrades rich
3. netcup Local Block Storage bestellen, einrichten und unter Linux einbinden