Jak provozovat Homarr na vlastním serveru v roce 2026: dashboardy, secrets a živé dlaždice

Kontejner Homarru může být ve stavu green, i když je rozbitá funkce, na které uživatelům záleží. U Homarru jde obvykle o skryté selhání, kdy widgety nemohou kontaktovat služby, protože používají adresy dostupné pouze z hostitele. Tento návod považuje za akceptační test následující scénář: „vytvořit nástěnku, přidat dlaždici služby, nakonfigurovat jednu integraci s přihlašovacími údaji a po restartu ověřit živý stav a vyhledávání“. Nasazení proto staví od tohoto výsledku zpět.

Homarr má v zásobníku konkrétní roli: vyhledávatelný dashboard s živými dlaždicemi pro self-hostované služby. Produkční otázkou tedy není, zda port 7575 jednou odpoví, ale zda budou stav, závislosti a veřejná adresa dál konzistentní po restartu, aktualizaci a obnovení ze zálohy.

Nejprve definujte, co znamená úspěch u Homarru

Nenechte image Homarru náhodou určovat produkční architekturu. Image poskytuje proces na portu 7575, ale úložiště, routing a externí požadavky stále potřebují promyšlené životní cykly. Požadavkem lokálního runtime je trvalá aplikační data a credentials pro živé integrace. To patří do plánu kapacity a mountů, včetně vlastníka a měřitelného limitu.

Nasazení je připravené na důkladnější testování, když dokáže vytvořit nástěnku, přidat dlaždici služby, nakonfigurovat jednu integraci s přihlašovacími údaji a po restartu ověřit živý stav a vyhledávání. Sledujte tuto transakci v logách a monitorujte fan-out požadavků widgetů, latenci downstream API, velikost aplikačních dat a počet současných klientů dashboardu. Tato pozorování ukážou, zda aktuální topologie izoluje správnou komponentu.

Nacvičte rizikovou změnu Homarru

Green kontejner je nutný, ale sám o sobě nestačí. SLI na úrovni služby představuje úspěšné dokončení scénáře „vytvořit nástěnku, přidat dlaždici služby, nakonfigurovat jednu integraci s přihlašovacími údaji a po restartu ověřit živý stav a vyhledávání“. Pravděpodobnými signály zatížení jsou fan-out požadavků widgetů, latence downstream API, velikost aplikačních dat a počet současných klientů dashboardu.

Change control je důležitý, protože migrace schématu Homarru a kontinuita šifrovacího klíče mohou ovlivnit uložené přihlašovací údaje integrací. Uchovejte předchozí image, migrace testujte nad kopií stavu a zdokumentujte, zda je po změně schématu podporován rollback. Pokud widgety nemohou kontaktovat služby, protože používají adresy dostupné pouze z hostitele, diagnostikujte první hranici, která se liší od funkčního prostředí.

Zaznamenejte známé funkční nasazení Homarru

Nepoužívejte první provozní provoz uživatelů jako akceptační test Homarru. Připravte neškodný ukázkový stav a spusťte celý scénář „vytvořit nástěnku, přidat dlaždici služby, nakonfigurovat jednu integraci s přihlašovacími údaji a po restartu ověřit živý stav a vyhledávání“. Poznamenejte si přesnou veřejnou URL, výsledek, referenci image a interval logů spojený s tímto během.

Nahraďte kontejner a zopakujte test bez nového vytvoření dat. Poté proveďte obnovu na prázdném hostiteli; podmínkou úspěšné obnovy je návrat nástěnek, uživatelů, integrací a vlastních assetů a opětovné připojení widgetů s přihlašovacími údaji. V každém průchodu sledujte fan-out požadavků widgetů, latenci downstream API, velikost aplikačních dat a počet současných klientů dashboardu a nastavte alert na zhoršení transakce, nikoli na metriky nečinného kontejneru.

Jedna závěrečná kontrola by měla záměrně selhat: odešlete neškodný vstup poblíž limitu zdroje nebo formátu souvisejícího s touto hranicí: widgety nemohou kontaktovat služby, protože používají adresy dostupné pouze z hostitele. Ověřte, že výsledná zpráva Homarru identifikuje relevantní hranici, místo aby spustila mazání dat nebo nekonečný restart. Obnovte platný stav a potvrďte, že stejná ukázková transakce opět proběhne úspěšně. Zařaďte toto krátké cvičení do checklistu pro release.

Spusťte první instanci odpovídající produkci

První kontejner by mělo být snadné smazat a znovu vytvořit. Data uchovávejte mimo zapisovatelnou vrstvu, port 7575 namapujte pouze tam, kam se dostane proxy, a konfiguraci předávejte za běhu.

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

Po úvodním testu image připněte na konkrétní verzi. Čtěte nejstarší chybu při startu, ne poslední zprávu o restartu, pomocí docker inspect ověřte každý mount a sledujte logy při vytváření nástěnky, přidávání dlaždice služby, konfiguraci jedné integrace s přihlašovacími údaji a ověřování živého stavu a vyhledávání po restartu. Tato sekvence rozliší chybný příkaz image od problému se závislostí nebo oprávněními.

Volumes jsou teprve první vrstvou obnovy

U Homarru začíná bezpečnost při redeployi u nástěnek, uživatelů, integrací, secrets a vlastních assetů. Před bootstrapem připojte /appdata, zapište neškodná ukázková data a nahraďte kontejner, abyste prokázali, že je tato cesta skutečně persistentní. Cestu otestujte nahrazením kontejneru v době, kdy ukázková data stále existují; odhalíte tak mounty ukazující o jeden adresář příliš vysoko nebo nízko.

Poté otestujte disaster recovery na prázdném hostiteli. Tam, kde je to potřeba, použijte export databáze konzistentní z pohledu aplikace a ověřte, že se vrátí nástěnky, uživatelé, integrace a vlastní assety a že se widgety s přihlašovacími údaji znovu připojí. Návod na zálohy databází ověřené obnovou představuje lepší cíl než pouhá kontrola, zda byl vytvořen archivní soubor.

Zabraňte tomu, aby úspěch proxy zakryl selhání aplikace

Prohlížeč, API klient i Homarr se musí shodnout na jednom originu. Aby tomu tak bylo, nastavte externí hostname pro HTTPS a povolené originy. Zachovejte původní host a protokol a zároveň ponechte port 7575 nedostupný jako konkurenční veřejnou adresu.

Návod pro řešení problémů, kdy je nasazení úspěšné, ale web nefunguje pomáhá rozlišit nedostupnou route od aplikace, která odpovídá. Toto rozlišení je zde důležité: widgety nemohou kontaktovat služby, protože používají adresy dostupné pouze z hostitele. Změny na ingressu opraví pouze první případ; druhý vyžaduje kontrolu logů, stavu nebo workloadu Homarru.

Uzavřete dočasný přístup pro nastavení

Bezpečné nasazení Homarru začíná odebráním oprávnění. Po uložení secrets integrací neměňte šifrovací klíč; místo toho ponechte SECRET_ENCRYPTION_KEY stabilní, chraňte úpravy nástěnek a omezte každý credential widgetu na nezbytný rozsah.

SECRET_ENCRYPTION_KEY vygenerujte jednou, neukládejte ho do Gitu a uchovejte ho spolu s recovery manifestem, protože jeho změna může zneplatnit zašifrovaný nebo podepsaný stav aplikace. Omezte administrátorské routy, pro závislosti používejte private DNS a zkontrolujte každý bind mount. Pokud se logy odesílají do centrálního systému, odstraňte secrets a soukromý obsah ještě před jejich opuštěním serveru.

Přesuňte opakovatelnou infrastrukturu do Dockupu

U Homarru je Dockup nejvíce užitečný na hranici mezi imagí a durable službou. Udržuje route na port 7575, TLS, hodnoty secrets a storage připojené i při nahrazování kontejnerů, ať už výpočetní prostředky poskytuje Dockup, nebo váš připojený server.

Závěr věnujte znalostem aplikace: nastavte externí hostname pro HTTPS a povolené originy, potvrďte lokální požadavek — trvalá aplikační data a credentials pro živé integrace — a spusťte toto ověření: vytvořte nástěnku, přidejte dlaždici služby, nakonfigurujte jednu integraci s přihlašovacími údaji a po restartu potvrďte živý stav a vyhledávání. Výsledek si ponechte jako deployment check, aby se další aktualizace image posuzovala podle chování, nikoli podle stavu kontejneru.

Často kladené otázky

Co Homarr potřebuje pro produkční nasazení?

Veďte kontejner Homarru na portu 7575 přes jeden HTTPS origin. Požadavkem lokálního runtime jsou trvalá aplikační data a credentials pro živé integrace. Homarr neoznačujte za připravený, dokud nedokážete vytvořit nástěnku, přidat dlaždici služby, nakonfigurovat jednu integraci s přihlašovacími údaji a po restartu potvrdit živý stav a vyhledávání.

Která data Homarru patří do zálohy?

Zachovejte /appdata a do stejného recovery manifestu zahrňte nástěnky, uživatele, integrace, secrets a vlastní assety. Čistá obnova Homarru je úspěšná pouze tehdy, když se vrátí nástěnky, uživatelé, integrace a vlastní assety a widgety s přihlašovacími údaji se znovu připojí.

Vyžaduje Homarr za reverse proxy HTTPS?

Pro veřejný origin Homarru používejte HTTPS a port 7575 ponechte na interní route. Nastavení Homarru aplikujte správně: nastavte externí hostname pro HTTPS a povolené originy. U Homarru HTTPS chrání credentials nebo uživatelský obsah při přenosu a udržuje konzistentní chování klienta závislé na originu.

Jak testovat aktualizaci Homarru?

Obnovte aktuální stav Homarru do izolovaného nasazení, použijte kandidátní verzi a zopakujte jeho akceptační transakci. Zvláštní pozornost věnujte tomu, že migrace schématu Homarru a kontinuita šifrovacího klíče mohou ovlivnit uložené přihlašovací údaje integrací. Předchozí image Homarru ponechte, dokud neporozumíte hranici migrace dat a rollbacku.