Jak hostować Homepage samodzielnie w 2026 roku: dozwolone hosty, widgety i konfiguracja

Istnieją dwie wersje „uruchomienia Homepage”: kontener działa albo usługa wykonuje swoje rzeczywiste zadanie. Liczy się tylko ta druga wersja. Dowodem jest wczytanie usług i zakładek, wywołanie kilku działających widgetów, przetestowanie wyszukiwania oraz restart po edycji pliku konfiguracyjnego YAML.

Homepage służy jako strona startowa z działającymi widgetami dla usług hostowanych samodzielnie. Wdrożenie musi zachować elementy stojące za tym działaniem; port, volume i certyfikat są danymi wejściowymi, a nie rezultatem.

Wybierz najmniejszą użyteczną topologię Homepage

Przydatny diagram Homepage pokazuje publiczną trasę, prywatny port 3000, granicę stanu oraz wszystkie wymagania pomocnicze. Zaznacz, które strzałki przenoszą dane uwierzytelniające, a które zwykły ruch użytkownika. Zewnętrznym wymaganiem Homepage jest konfiguracja tylko do odczytu oraz dane uwierzytelniające dla opcjonalnych widgetów usług. Przetestuj wychodzący DNS, TLS i działanie dostawców bez publikowania kolejnej usługi przychodzącej.

Potwierdź diagram jednym rzeczywistym działaniem: wczytaj usługi i zakładki, wywołaj kilka działających widgetów, przetestuj wyszukiwanie oraz zrestartuj usługę po edycji pliku konfiguracyjnego YAML. Największe obciążenie prawdopodobnie wynika z liczby wywołań widgetów, powolnych API usług downstream, rozwiązywania DNS oraz częstotliwości odświeżania dashboardu w przeglądarce; monitoruj tę ścieżkę, zamiast traktować wszystkie żądania HTTP jednakowo.

Aktualizuj Homepage bez zgadywania

Pierwszą użyteczną metryką operacyjną dla Homepage jest to, czy może wczytać usługi i zakładki, wywołać kilka działających widgetów, przetestować wyszukiwanie oraz zrestartować usługę po edycji pliku konfiguracyjnego YAML. Połącz ją z sygnałami nasycenia dotyczącymi liczby wywołań widgetów, powolnych API usług downstream, rozwiązywania DNS oraz częstotliwości odświeżania dashboardu w przeglądarce. Probe sprawdzający wyłącznie proces nie powinien wywoływać kosztownych zależności ani restartować kontenera tylko dlatego, że usługa upstream jest chwilowo niedostępna.

Traktuj aktualizacje jako zmiany danych, ponieważ klucze konfiguracji i integracje widgetów mogą się zmieniać, dlatego przed aktualizacją obrazu zweryfikuj YAML oraz działanie dostawców. Przypinaj wersje, przeprowadzaj próby na odtworzonym stanie i zachowaj poprzedni obraz do czasu, aż rollback będzie nadal możliwy. Gdy host zostanie odrzucony albo wcięcia YAML uniemożliwią wczytanie konfiguracji, zachowaj logi sprzed restartu; zwykle zawierają komunikat wskazujący przyczynę.

Produkcyjny test akceptacyjny Homepage

Zanim pojawią się prawdziwi użytkownicy, przygotuj arkusz wydania dla Homepage. Musi on zawierać przypięty obraz, port 3000, canonical origin, ścieżki trwałych danych oraz właściciela konfiguracji tylko do odczytu i danych uwierzytelniających dla opcjonalnych widgetów usług. Dołącz oczekiwany rezultat tej transakcji: wczytanie usług i zakładek, wywołanie kilku działających widgetów, przetestowanie wyszukiwania oraz restart po edycji pliku konfiguracyjnego YAML.

Użyj arkusza po standardowej wymianie oraz po czystym odtworzeniu. Odzyskiwanie można uznać za zakończone powodzeniem tylko wtedy, gdy wrócą usługi, zakładki, widgety i niestandardowe assety, a wszystkie krytyczne widgety będą w widoczny sposób obsługiwać awarie usług downstream. Zbierz także krótki ślad zasobów obejmujący liczbę wywołań widgetów, powolne API usług downstream, rozwiązywanie DNS oraz częstotliwość odświeżania dashboardu w przeglądarce; przechowuj go obok wydania, aby przyszłe zmiany pojemności porównywać przy tym samym obciążeniu.

Uwzględnij jedną kontrolowaną awarię: tymczasowo zablokuj ścieżkę testową używaną przez konfigurację tylko do odczytu i dane uwierzytelniające dla opcjonalnych widgetów usług. Potwierdź, że Homepage zgłasza problem na właściwej granicy, przywróć poprawne warunki i ponownie wykonaj transakcję. Sprawdza to widoczność błędów, a nie tylko powodzenie, i zapobiega sytuacji, w której zdrowo wyglądający interfejs ukrywa uszkodzony worker, callback albo połączenie z bazą danych.

Zapewnij powtarzalny start Homepage

Traktuj kontener jako wymienne środowisko uruchomieniowe, a nie jako miejsce przechowywania źródła prawdy.

docker run -d \
  --name homepage \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v homepage-data:/app/config \
  -e HOMEPAGE_ALLOWED_HOSTS=home.example.com \
  ghcr.io/gethomepage/homepage:latest

Zezwól na wymaganą ścieżkę wychodzącą lub ścieżkę po stronie klienta dla konfiguracji tylko do odczytu i danych uwierzytelniających opcjonalnych widgetów usług oraz zweryfikuj jej działanie. Przed udostępnieniem usługi sprawdź użytkownika kontenera, ścieżki z prawem zapisu i nasłuchujący listener. Wykonaj pełne działanie — wczytaj usługi i zakładki, wywołaj kilka działających widgetów, przetestuj wyszukiwanie oraz zrestartuj usługę po edycji pliku konfiguracyjnego YAML — i zapisz dokładne odwołanie do obrazu, które dało ten rezultat.

Oddziel wymienne kontenery od trwałych danych

Trwały zestaw do odtworzenia obejmuje pliki konfiguracyjne, zakładki, usługi i niestandardowe assety. Zamontuj /app/config przed bootstrapem, zapisz nieszkodliwe przykładowe dane i wymień kontener, aby potwierdzić, że ta ścieżka rzeczywiście jest trwała. Volume chroni dane przed wymianą kontenera, ale nie przed utratą hosta, przypadkowym usunięciem ani uszkodzeniem na poziomie aplikacji.

Twórz backupy z uwzględnieniem źródła danych: gdy jest to wymagane, używaj logical dumps dla działających baz danych, a pliki kopiuj wyłącznie ze spójnego stanu. Przechowuj jedną zaszyfrowaną kopię poza hostem Homepage. Kryterium akceptacji odtworzenia musi być konkretne — usługi, zakładki, widgety i niestandardowe assety muszą wrócić, a wszystkie krytyczne widgety muszą w widoczny sposób obsługiwać awarie usług downstream. Poradnik backupów przetestowanych przez odtworzenie wyjaśnia, dlaczego sam status powodzenia zadania nie wystarcza.

Domeny, nagłówki proxy i port 3000

Przeglądarka, klient API i Homepage muszą uzgadniać jeden origin. Aby to zapewnić, ustaw dozwolone hosty dla dokładnej domeny i nazwy hosta proxy. Zachowaj oryginalny host i protokół, jednocześnie nie udostępniając portu 3000 jako konkurencyjnego publicznego adresu.

Poradnik rozwiązywania problemów z niedostępną stroną pomaga odróżnić nieosiągalną trasę od odpowiadającej aplikacji. To rozróżnienie ma tutaj znaczenie: host zostaje odrzucony albo wcięcia YAML uniemożliwiają wczytanie konfiguracji. Tylko pierwszy problem można naprawić zmianami w ingressie; drugi wymaga sprawdzenia logów Homepage, stanu lub obciążenia.

Decyzje dotyczące bezpieczeństwa właściwe dla Homepage

Nie przejmuj założeń dotyczących bezpieczeństwa z lokalnego tutoriala. Specyficznym problemem Homepage jest umieszczanie kluczy API widgetów w publicznym repozytorium. W środowisku produkcyjnym należy więc precyzyjnie ustawić dozwolone hosty, a klucze API widgetów przechowywać w zmiennych środowiskowych lub konfiguracji opartej na sekretach, a nie w publicznym repozytorium.

HOMEPAGE_ALLOWED_HOSTS steruje działaniem, a nie poufnością; zweryfikuj jego typ i wartość, a właściwe dane uwierzytelniające Homepage przechowuj osobno. Ogranicz dostęp do systemu plików i sieci, chroń endpointy konfiguracyjne oraz zdefiniuj limity uploadu, żądań lub wykonywania dla liczby wywołań widgetów, powolnych API usług downstream, rozwiązywania DNS i częstotliwości odświeżania dashboardu w przeglądarce.

Gdzie Dockup ogranicza nakład pracy przy Homepage

W przypadku Homepage Dockup jest najbardziej użyteczny na granicy między obrazem a trwałą usługą. Utrzymuje trasę do portu 3000, TLS, wartości sekretów i storage po wymianie kontenerów, niezależnie od tego, czy compute należy do Dockup, czy do podłączonego serwera.

Na końcu wykorzystaj wiedzę o aplikacji: ustaw dozwolone hosty dla dokładnej domeny i nazwy hosta proxy; zezwól na konfigurację tylko do odczytu oraz dane uwierzytelniające dla opcjonalnych widgetów usług i zweryfikuj ich działanie; następnie wykonaj ten test: wczytaj usługi i zakładki, wywołaj kilka działających widgetów, przetestuj wyszukiwanie oraz zrestartuj usługę po edycji pliku konfiguracyjnego YAML. Zachowaj wynik jako kontrolę wdrożenia, aby kolejną aktualizację obrazu oceniać na podstawie działania, a nie statusu kontenera.

Najczęściej zadawane pytania

Czego Homepage potrzebuje do wdrożenia produkcyjnego?

Skieruj kontener Homepage na porcie 3000 przez jeden origin HTTPS. Zewnętrznym wymaganiem dostarczania usługi jest konfiguracja tylko do odczytu oraz dane uwierzytelniające dla opcjonalnych widgetów usług. Nie uznawaj Homepage za gotowe, dopóki nie możesz wczytać usług i zakładek, wywołać kilku działających widgetów, przetestować wyszukiwania oraz zrestartować usługi po edycji pliku konfiguracyjnego YAML.

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

Utrwal /app/config i uwzględnij pliki konfiguracyjne, zakładki, usługi oraz niestandardowe assety w tym samym manifeście odtwarzania. Czyste odtworzenie Homepage kończy się powodzeniem tylko wtedy, gdy wrócą usługi, zakładki, widgety i niestandardowe assety, a wszystkie krytyczne widgety będą w widoczny sposób obsługiwać awarie usług downstream.

Czy Homepage wymaga HTTPS za reverse proxy?

Używaj HTTPS dla publicznego originu Homepage, a port 3000 pozostaw na wewnętrznej trasie. Zastosuj poprawnie ustawienie Homepage: skonfiguruj dozwolone hosty dla dokładnej domeny i nazwy hosta proxy. W przypadku Homepage HTTPS chroni dane uwierzytelniające lub treści użytkowników podczas przesyłania i zapewnia spójne działanie klienta zależne od originu.

Jak testować aktualizację Homepage?

Odtwórz bieżący stan Homepage w odizolowanym wdrożeniu, zastosuj wersję kandydującą i powtórz transakcję akceptacyjną. Zwróć szczególną uwagę na fakt, że klucze konfiguracji i integracje widgetów mogą się zmieniać, dlatego przed aktualizacją obrazu zweryfikuj YAML oraz działanie dostawców. Zachowaj poprzedni obraz Homepage do czasu poznania granic migracji danych i rollbacku.