Jak hostować Homarr samodzielnie w 2026 roku: dashboardy, sekrety i kafelki na żywo

Kontener Homarr może działać poprawnie, mimo że funkcja, na której zależy użytkownikom, jest niesprawna. W przypadku Homarr ukryta awaria najczęściej polega na tym, że widgety nie mogą połączyć się z usługami, ponieważ korzystają z adresów lokalnych hosta. W tym poradniku jako test akceptacyjny traktujemy pełną sekwencję: „utwórz tablicę, dodaj kafelek usługi, skonfiguruj jedną integrację wymagającą uwierzytelnienia oraz potwierdź działanie statusu na żywo i wyszukiwania po restarcie” — a następnie projektujemy wdrożenie od końca, zaczynając od tego rezultatu.

Homarr pełni w stacku konkretną rolę: jest przeszukiwalnym dashboardem z kafelkami na żywo dla usług hostowanych samodzielnie. Pytanie dotyczące środowiska produkcyjnego nie brzmi więc: czy port 7575 odpowiada jednorazowo, lecz czy stan, zależności i publiczny adres nadal pozostają spójne po restarcie, aktualizacji i odtworzeniu.

Najpierw zdefiniuj, co oznacza sukces w Homarr

Nie pozwól, aby obraz Homarr przypadkowo narzucił architekturę produkcyjną. Obraz dostarcza proces działający na porcie 7575, ale pamięć masowa, routing i wymagania zewnętrzne nadal potrzebują świadomie zaplanowanych cykli życia. Lokalne wymaganie runtime to trwałe dane aplikacji oraz dane uwierzytelniające dla integracji działających na żywo. Powinno to znaleźć odzwierciedlenie w planie pojemności i mountów, wraz z właścicielem oraz mierzalnym limitem.

Wdrożenie jest gotowe do dokładniejszych testów, gdy można utworzyć tablicę, dodać kafelek usługi, skonfigurować jedną integrację wymagającą uwierzytelnienia oraz potwierdzić działanie statusu na żywo i wyszukiwania po restarcie. Śledź tę transakcję w logach i obserwuj rozgałęzienie żądań widgetów, opóźnienie API usług zależnych, rozmiar danych aplikacji oraz liczbę równoczesnych klientów dashboardu. Obserwacje te pokażą, czy obecna topologia odseparowuje właściwy komponent.

Przećwicz ryzykowną zmianę w Homarr

Działający kontener jest konieczny, ale niewystarczający. Wskaźnikiem na poziomie usługi jest pomyślne zakończenie sekwencji „utwórz tablicę, dodaj kafelek usługi, skonfiguruj jedną integrację wymagającą uwierzytelnienia oraz potwierdź działanie statusu na żywo i wyszukiwania po restarcie”, a prawdopodobnymi sygnałami przeciążenia są rozgałęzienie żądań widgetów, opóźnienie API usług zależnych, rozmiar danych aplikacji oraz liczba równoczesnych klientów dashboardu.

Kontrola zmian ma znaczenie, ponieważ migracje schematu Homarr i ciągłość klucza szyfrowania mogą wpływać na zapisane dane uwierzytelniające integracji. Zachowaj poprzedni obraz, testuj migracje na skopiowanym stanie i udokumentuj, czy wycofanie zmiany jest obsługiwane po migracji schematu. Jeśli widgety nie mogą połączyć się z usługami, ponieważ korzystają z adresów lokalnych hosta, zdiagnozuj pierwszą granicę, która różni się od działającego środowiska.

Zapisz sprawdzoną konfigurację wdrożenia Homarr

Nie traktuj ruchu pierwszego użytkownika jako testu akceptacyjnego Homarr. Przygotuj nieszkodliwy przykładowy stan i wykonaj pełną sekwencję „utwórz tablicę, dodaj kafelek usługi, skonfiguruj jedną integrację wymagającą uwierzytelnienia oraz potwierdź działanie statusu na żywo i wyszukiwania po restarcie”. Zapisz dokładny publiczny URL, rezultat, referencję obrazu oraz przedział logów powiązany z tym przebiegiem.

Usuń kontener i odtwórz go, nie przebudowując danych. Następnie odtwórz środowisko na pustym hoście; warunkiem poprawnego odtworzenia jest powrót tablic, użytkowników, integracji i własnych assetów oraz ponowne połączenie widgetów wymagających uwierzytelnienia. Za każdym razem obserwuj rozgałęzienie żądań widgetów, opóźnienie API usług zależnych, rozmiar danych aplikacji oraz liczbę równoczesnych klientów dashboardu. Zdefiniuj alert dotyczący pogorszenia działania transakcji, a nie bezczynnych metryk kontenera.

Jeden końcowy test powinien celowo zakończyć się niepowodzeniem: wprowadź nieszkodliwe dane w pobliżu limitu zasobów lub formatu powiązanego z tą granicą: widgety nie mogą połączyć się z usługami, ponieważ korzystają z adresów lokalnych hosta. Sprawdź, czy komunikat Homarr wskazuje właściwą granicę, zamiast uruchamiać usuwanie danych lub niekończący się restart. Przywróć poprawne warunki i potwierdź, że ta sama przykładowa transakcja kończy się powodzeniem. Dodaj to krótkie ćwiczenie do checklisty wydania.

Uruchom pierwszą instancję zbliżoną do produkcyjnej

Pierwszy kontener powinien być łatwy do usunięcia i odtworzenia. Przechowuj dane poza warstwą zapisu kontenera, udostępniaj port 7575 tylko tam, gdzie może dotrzeć proxy, i przekazuj konfigurację w runtime.

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 pierwszym teście przypnij konkretną wersję obrazu. Odczytaj najwcześniejszy błąd uruchamiania zamiast końcowego komunikatu o restarcie, zweryfikuj każdy mount za pomocą docker inspect i śledź logi podczas tworzenia tablicy, dodawania kafelka usługi, konfigurowania jednej integracji wymagającej uwierzytelnienia oraz potwierdzania działania statusu na żywo i wyszukiwania po restarcie. Ta sekwencja pozwala odróżnić błędne polecenie uruchomienia obrazu od problemu z zależnością lub uprawnieniami.

Volumes to dopiero pierwsza warstwa odtwarzania

W przypadku Homarr bezpieczeństwo ponownego wdrożenia zaczyna się od tablic, użytkowników, integracji, sekretów i własnych assetów. Zamontuj /appdata przed bootstrapem, zapisz nieszkodliwe przykładowe dane i usuń oraz odtwórz kontener, aby potwierdzić, że ta ścieżka rzeczywiście jest trwała. Przetestuj ją, usuwając kontener, gdy przykładowe dane nadal istnieją; ujawni to mounty wskazujące o jeden katalog za wysoko lub za nisko.

Następnie przetestuj odtwarzanie po awarii na pustym hoście. W razie potrzeby użyj spójnego z aplikacją eksportu bazy danych i zweryfikuj, czy tablice, użytkownicy, integracje i własne assety wracają oraz czy widgety wymagające uwierzytelnienia ponownie się łączą. Poradnik dotyczący backupów baz danych przetestowanych przez odtworzenie wyznacza lepszy cel niż samo sprawdzenie, czy został utworzony plik archiwum.

Nie pozwól, aby sukces proxy maskował awarię aplikacji

Przeglądarka, klient API i Homarr muszą korzystać z tego samego originu. Aby to zapewnić, ustaw zewnętrzny hostname HTTPS oraz dozwolone originy. Zachowaj oryginalny host i protokół, jednocześnie pozostawiając port 7575 niedostępny jako konkurencyjny publiczny adres.

Poradnik rozwiązywania problemów z niedostępną witryną pomaga odróżnić niedostępną trasę od aplikacji, która odpowiada. To rozróżnienie ma tutaj znaczenie: widgety nie mogą połączyć się z usługami, ponieważ korzystają z adresów lokalnych hosta. Zmiany w ingress naprawiają tylko pierwszy problem; drugi wymaga analizy logów Homarr, stanu lub obciążenia.

Zamknij tymczasowy dostęp konfiguracyjny

Bezpieczne wdrożenie Homarr zaczyna się od odebrania nadmiarowych uprawnień. Unikaj zmiany klucza szyfrowania po zapisaniu sekretów integracji; zamiast tego utrzymuj SECRET_ENCRYPTION_KEY bez zmian, chroń możliwość edycji tablic i ograniczaj zakres poświadczeń każdego widgetu.

Wygeneruj SECRET_ENCRYPTION_KEY raz, nie przechowuj go w Git i zachowaj go w manifeście odtwarzania, ponieważ zmiana może unieważnić zaszyfrowany lub podpisany stan aplikacji. Ogranicz trasy administracyjne, używaj prywatnego DNS dla zależności i przejrzyj każdy bind mount. Gdy logi są wysyłane centralnie, filtruj sekrety i prywatne treści, zanim opuszczą serwer.

Przenieś powtarzalne prace infrastrukturalne do Dockup

W przypadku Homarr Dockup jest najbardziej przydatny na granicy między obrazem a trwałą usługą. Utrzymuje trasę do 7575, TLS, wartości sekretów i storage między wymianami kontenerów — niezależnie od tego, czy compute należy do Dockup, czy do podłączonego serwera.

Zakończ wdrożenie, uwzględniając wiedzę o aplikacji: ustaw zewnętrzny hostname HTTPS oraz dozwolone originy; potwierdź lokalne wymaganie — trwałe dane aplikacji oraz dane uwierzytelniające dla integracji działających na żywo; i wykonaj następującą weryfikację: utwórz tablicę, dodaj kafelek usługi, skonfiguruj jedną integrację wymagającą uwierzytelnienia oraz potwierdź działanie statusu na żywo i wyszukiwania po restarcie. Zachowaj wynik jako kontrolę wdrożenia, aby kolejna aktualizacja obrazu była oceniana na podstawie działania, a nie statusu kontenera.

Najczęściej zadawane pytania

Czego Homarr potrzebuje do wdrożenia produkcyjnego?

Przekieruj kontener Homarr działający na porcie 7575 przez jeden origin HTTPS. Lokalne wymaganie runtime to trwałe dane aplikacji oraz dane uwierzytelniające dla integracji działających na żywo. Nie uznawaj Homarr za gotowy, dopóki nie możesz utworzyć tablicy, dodać kafelka usługi, skonfigurować jednej integracji wymagającej uwierzytelnienia oraz potwierdzić działania statusu na żywo i wyszukiwania po restarcie.

Które dane Homarr powinny znaleźć się w backupie?

Utrwal /appdata i uwzględnij tablice, użytkowników, integracje, sekrety oraz własne assety w tym samym manifeście odtwarzania. Czyste odtworzenie Homarr kończy się powodzeniem tylko wtedy, gdy tablice, użytkownicy, integracje i własne assety wrócą, a widgety wymagające uwierzytelnienia ponownie się połączą.

Czy Homarr wymaga HTTPS za reverse proxy?

Używaj HTTPS dla publicznego originu Homarr i pozostaw port 7575 na wewnętrznej trasie. Skonfiguruj poprawnie ustawienie Homarr: ustaw zewnętrzny hostname HTTPS oraz dozwolone originy. W przypadku Homarr HTTPS chroni poświadczenia lub treści użytkowników przesyłane w tranzycie i zapewnia spójne działanie klienta zależne od originu.

Jak testować aktualizację Homarr?

Odtwórz bieżący stan Homarr w odizolowanym wdrożeniu, zastosuj wersję kandydującą i powtórz transakcję akceptacyjną. Zwróć szczególną uwagę na to, że migracje schematu Homarr i ciągłość klucza szyfrowania mogą wpływać na zapisane dane uwierzytelniające integracji. Zachowaj poprzedni obraz Homarr do czasu zrozumienia granicy migracji danych i możliwości wycofania zmiany.