Homarr 2026 selbst hosten: Dashboards, Secrets und Live-Tiles

Ein Homarr-Container kann grün sein, während die Funktion, auf die es den Benutzern ankommt, nicht funktioniert. Bei Homarr besteht dieser versteckte Fehler meist darin, dass Widgets keine Services erreichen können, weil sie hostlokale Adressen verwenden. Dieser Leitfaden betrachtet „ein Board erstellen, eine Service-Kachel hinzufügen, eine Integration mit Zugangsdaten konfigurieren und nach einem Neustart den Live-Status und die Suche bestätigen“ als Abnahmetest und leitet die Bereitstellung von diesem Ergebnis aus rückwärts ab.

Homarr hat im Stack eine klar definierte Rolle: ein durchsuchbares Dashboard mit Live-Kacheln für selbst gehostete Services. Die Frage für den Produktivbetrieb lautet daher nicht, ob Port 7575 einmal antwortet, sondern ob Status, Abhängigkeiten und öffentliche Adresse nach einem Neustart, Update und Restore weiterhin übereinstimmen.

Erfolg für Homarr zuerst definieren

Lass nicht zu, dass das Homarr-Image versehentlich die Produktionsarchitektur vorgibt. Das Image stellt einen Prozess auf Port 7575 bereit; Storage, Routing und externe Anforderungen benötigen weiterhin bewusst geplante Lebenszyklen. Die lokale Laufzeitanforderung besteht aus persistenten App-Daten und Zugangsdaten für Live-Integrationen. Das gehört in den Kapazitäts- und Mount-Plan – mit einem Verantwortlichen und einem messbaren Limit.

Die Bereitstellung ist bereit für weiterführende Tests, wenn sie ein Board erstellen, eine Service-Kachel hinzufügen, eine Integration mit Zugangsdaten konfigurieren und nach einem Neustart den Live-Status und die Suche bestätigen kann. Verfolge die Transaktion in den Logs und beobachte die Anzahl der Widget-Requests, die Latenz nachgelagerter APIs, die Größe der App-Daten und die Anzahl gleichzeitiger Dashboard-Clients. Diese Beobachtungen zeigen, ob die aktuelle Topologie die richtige Komponente isoliert.

Die riskante Homarr-Änderung proben

Ein grüner Container ist notwendig, aber nicht ausreichend. Der Service-Level-Indikator ist der erfolgreiche Abschluss von „ein Board erstellen, eine Service-Kachel hinzufügen, eine Integration mit Zugangsdaten konfigurieren und nach einem Neustart den Live-Status und die Suche bestätigen“. Wahrscheinliche Belastungssignale sind dabei die Anzahl der Widget-Requests, die Latenz nachgelagerter APIs, die Größe der App-Daten und die Anzahl gleichzeitiger Dashboard-Clients.

Change Control ist wichtig, weil Homarr-Schema-Migrationen und die Kontinuität des Verschlüsselungsschlüssels gespeicherte Zugangsdaten für Integrationen beeinflussen können. Bewahre das alte Image auf, teste Migrationen mit einer Kopie des Status und dokumentiere, ob nach der Schemaänderung ein Rollback unterstützt wird. Wenn Widgets keine Services erreichen können, weil sie hostlokale Adressen verwenden, diagnostiziere die erste Grenze, die sich von der funktionierenden Umgebung unterscheidet.

Eine funktionierende Homarr-Bereitstellung dokumentieren

Mache den Traffic des ersten Benutzers nicht zum Abnahmetest für Homarr. Bereite harmlose Beispieldaten vor und führe die vollständige Aktion „ein Board erstellen, eine Service-Kachel hinzufügen, eine Integration mit Zugangsdaten konfigurieren und nach einem Neustart den Live-Status und die Suche bestätigen“ aus. Notiere die exakte öffentliche URL, das Ergebnis, die Image-Referenz und das mit dem Lauf verbundene Log-Zeitfenster.

Ersetze den Container und wiederhole den Test, ohne die Daten neu zu erstellen. Stelle anschließend auf einem leeren Host wieder her; die Wiederherstellungsbedingung ist, dass Boards, Benutzer, Integrationen und benutzerdefinierte Assets zurückkehren und Widgets mit Zugangsdaten sich wieder verbinden. Beobachte bei jedem Durchlauf die Anzahl der Widget-Requests, die Latenz nachgelagerter APIs, die Größe der App-Daten und die Anzahl gleichzeitiger Dashboard-Clients. Definiere einen Alert anhand der Verschlechterung der Transaktion statt anhand von Metriken eines inaktiven Containers.

Eine letzte Prüfung sollte absichtlich fehlschlagen: Sende harmlose Eingaben nahe am Ressourcen- oder Formatlimit, das mit dieser Grenze verbunden ist: Widgets können keine Services erreichen, weil sie hostlokale Adressen verwenden. Überprüfe, dass die resultierende Homarr-Meldung die relevante Grenze identifiziert, statt eine Datenlöschung oder einen endlosen Neustart auszulösen. Stelle den gültigen Zustand wieder her und bestätige, dass dieselbe Beispieltransaktion erfolgreich ist. Nimm diese kurze Übung in die Release-Checkliste auf.

Die erste produktionsnahe Instanz starten

Der erste Container sollte sich einfach löschen und neu erstellen lassen. Halte Daten außerhalb der beschreibbaren Schicht, binde Port 7575 nur dort, wo der Proxy ihn erreichen kann, und übergib die Konfiguration zur Laufzeit.

docker run -d \
  --name homarr \
  --restart unless-stopped \
  -p 127.0.0.1:7575:7575 \
  -v homarr-data:/appdata \
  -e SECRET_ENCRYPTION_KEY=replace-with-a-long-random-value \
  ghcr.io/homarr-labs/homarr:latest

Fixiere das Image nach dem ersten Test auf eine Version. Lies den frühesten Startfehler statt der abschließenden Neustartmeldung, überprüfe jeden Mount mit docker inspect und verfolge die Logs, während du ein Board erstellst, eine Service-Kachel hinzufügst, eine Integration mit Zugangsdaten konfigurierst und nach einem Neustart den Live-Status und die Suche bestätigst. Diese Abfolge unterscheidet einen fehlerhaften Image-Befehl von einem Abhängigkeits- oder Berechtigungsproblem.

Volumes sind nur die erste Wiederherstellungsebene

Bei Homarr beginnt die Sicherheit von Redeployments mit Boards, Benutzern, Integrationen, Secrets und benutzerdefinierten Assets. Mount /appdata vor dem Bootstrap ein, schreibe harmlose Beispieldaten und ersetze den Container, um zu beweisen, dass dieser Pfad tatsächlich persistent ist. Teste den Pfad, indem du den Container ersetzt, solange harmlose Beispieldaten vorhanden sind. So werden Mounts sichtbar, die eine Verzeichnisebene zu hoch oder zu niedrig angesetzt sind.

Teste anschließend die Notfallwiederherstellung auf einem leeren Host. Verwende, falls erforderlich, einen anwendungskonsistenten Datenbankexport und überprüfe, dass Boards, Benutzer, Integrationen und benutzerdefinierte Assets zurückkehren und Widgets mit Zugangsdaten sich wieder verbinden. Der Leitfaden für Backups von Datenbanken, die du bereits wiederhergestellt hast bietet ein belastbareres Ziel, als lediglich zu prüfen, ob eine Archivdatei erstellt wurde.

Verhindern, dass ein erfolgreicher Proxy einen Anwendungsfehler verdeckt

Browser, API-Client und Homarr müssen sich auf eine gemeinsame Origin einigen. Stelle dafür den externen HTTPS-Hostnamen und die erlaubten Origins ein. Bewahre den ursprünglichen Host und das ursprüngliche Protokoll, während Port 7575 als konkurrierende öffentliche Adresse nicht verfügbar bleibt.

Der Leitfaden zur Fehlerbehebung bei ausgefallenen Websites hilft dabei, eine nicht erreichbare Route von einer antwortenden Anwendung zu unterscheiden. Diese Unterscheidung ist hier wichtig: Widgets können keine Services erreichen, weil sie hostlokale Adressen verwenden. Nur der erste Fall lässt sich durch Änderungen am Ingress beheben; der zweite erfordert eine Untersuchung der Homarr-Logs, des Status oder der Workload.

Temporären Setup-Zugriff schließen

Eine sichere Homarr-Bereitstellung beginnt damit, Berechtigungen zu reduzieren. Ändere den Verschlüsselungsschlüssel nicht mehr, nachdem Integrations-Secrets gespeichert wurden. Halte stattdessen SECRET_ENCRYPTION_KEY stabil, schütze die Bearbeitung von Boards und beschränke jede Widget-Zugabe auf den erforderlichen Umfang.

Erzeuge SECRET_ENCRYPTION_KEY einmal, halte ihn aus Git heraus und bewahre ihn zusammen mit dem Recovery-Manifest auf, da eine Änderung verschlüsselte oder signierte Anwendungsdaten unbrauchbar machen kann. Beschränke administrative Routen, verwende private DNS-Einträge für Abhängigkeiten und überprüfe jeden Bind-Mount. Wenn Logs zentral gesammelt werden, filtere Secrets und private Inhalte, bevor sie den Server verlassen.

Wiederkehrende Infrastrukturarbeiten zu Dockup verlagern

Für Homarr ist Dockup besonders an der Grenze zwischen einem Image und einem dauerhaften Service nützlich. Es hält die Route zu Port 7575, TLS, Secret-Werte und Storage bei Container-Ersetzungen zusammen – unabhängig davon, ob die Compute-Ressourcen zu Dockup oder zu deinem angebundenen Server gehören.

Schließe mit anwendungsspezifischem Wissen ab: Stelle den externen HTTPS-Hostnamen und die erlaubten Origins ein, bestätige die lokale Anforderung – persistente App-Daten plus Zugangsdaten für Live-Integrationen – und führe diese Prüfung durch: ein Board erstellen, eine Service-Kachel hinzufügen, eine Integration mit Zugangsdaten konfigurieren und nach einem Neustart den Live-Status und die Suche bestätigen. Bewahre das Ergebnis als Deployment-Check auf, damit das nächste Image-Update anhand des Verhaltens und nicht anhand des Containerstatus bewertet wird.

Häufig gestellte Fragen

Was benötigt Homarr für eine produktive Bereitstellung?

Leite den Homarr-Container über eine einzige HTTPS-Origin auf Port 7575. Die lokale Laufzeitanforderung besteht aus persistenten App-Daten und Zugangsdaten für Live-Integrationen. Betrachte Homarr erst dann als bereit, wenn du ein Board erstellen, eine Service-Kachel hinzufügen, eine Integration mit Zugangsdaten konfigurieren und nach einem Neustart den Live-Status und die Suche bestätigen kannst.

Welche Homarr-Daten gehören in ein Backup?

Mache /appdata persistent und nimm Boards, Benutzer, Integrationen, Secrets und benutzerdefinierte Assets in dasselbe Recovery-Manifest auf. Ein sauberer Homarr-Restore ist erst erfolgreich, wenn Boards, Benutzer, Integrationen und benutzerdefinierte Assets zurückkehren und Widgets mit Zugangsdaten sich wieder verbinden.

Benötigt Homarr hinter einem Reverse Proxy HTTPS?

Verwende HTTPS für die öffentliche Homarr-Origin und halte Port 7575 auf der internen Route. Wende die Homarr-Einstellung korrekt an: Stelle den externen HTTPS-Hostnamen und die erlaubten Origins ein. Bei Homarr schützt HTTPS Zugangsdaten oder Benutzerinhalte bei der Übertragung und sorgt für ein konsistentes, Origin-sensitives Verhalten des Clients.

Wie sollte ein Homarr-Upgrade getestet werden?

Stelle den aktuellen Homarr-Status in einer isolierten Bereitstellung wieder her, wende die Kandidatenversion an und wiederhole die Abnahmetransaktion. Achte besonders darauf, dass Homarr-Schema-Migrationen und die Kontinuität des Verschlüsselungsschlüssels gespeicherte Zugangsdaten für Integrationen beeinflussen können. Bewahre das vorherige Homarr-Image auf, bis die Grenzen der Datenmigration und des Rollbacks geklärt sind.