Homarr w CasaOS/ZimaOS: obecna konfiguracja Docker Compose

Podsumowanie: korzystaj z aktualnej ścieżki Docker Compose dla Homarr zamiast szablonu BigBear z 2023 roku

Stary artykuł CasaOS był przydatny, gdy BigBearCasaOS pakował Homarr do instalacji jednym kliknięciem. Homarr znacznie się zmienił. Obecny sposób samodzielnego hostowania korzysta z Compose i przechowuje stan w /appdatawymaga zmiennej SECRET_ENCRYPTION_KEYi opcjonalnie może montować gniazdo Dockera na potrzeby integracji z kontenerami.

Rozpocznij od trwałej definicji Compose

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    ports:
      - "7575:7575"
    volumes:
      - /DATA/AppData/homarr:/appdata
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - SECRET_ENCRYPTION_KEY=REPLACE_WITH_64_HEX_CHARS

Aktualna instalacja Homarr w Dockerze zaleca Compose i opisuje katalog /appdata.

Wygeneruj klucz szyfrowania przed pierwszym uruchomieniem

openssl rand -hex 32

Homarr używa tego sekretu do ochrony poufnych danych integracji. Przechowuj go poza publicznie eksportowanymi plikami Compose. Bezpieczne generowanie losowe w OpenSSL wyjaśnia to polecenie.

Montuj gniazdo Dockera tylko wtedy, gdy jest potrzebne

Gniazdo Dockera zapewnia szeroką kontrolę nad hostem. Jeśli Homarr potrzebuje tylko linków, zakładek i zewnętrznych widżetów, pomiń je. Dodaj je tylko w przypadku celowo używanych integracji obsługujących Dockera.

Używaj ZimaOS OpenAPI do danych ZimaOS

W przypadku danych o pamięci masowej lub stanie systemu korzystaj z opublikowanego interfejsu ZimaOS OpenAPI, zamiast analizować kod HTML panelu. Wymagania aplikacji ZimaOS obejmują planowanie zasobów.

Zachowaj Homarr wewnątrz sieci, dopóki uwierzytelnianie nie będzie gotowe

Panel może ujawniać wewnętrzne adresy IP, porty i stan infrastruktury. Nie publikuj go bezpośrednio bez uwierzytelniania i HTTPS. Pośredniczenie HTTPS w ZimaOS zapewnia warstwę dostępu publicznego.

Aktualizacja Homarr jako kontenera

docker compose down
docker compose pull
docker compose up -d

Trwałe /appdata przetrwa odtworzenie. Dlatego wolumen jest ważniejszy niż zachowanie starego kontenera.

Nie przechowuj konfiguracji Homarr wyłącznie w kontenerze

Jeśli /appdata nie jest mapowany na trwały magazyn hosta, ponowne utworzenie kontenera może usunąć konfigurację. Wykonuj kopię zapasową folderu Homarr po stronie hosta. Kopia zapasowa ZimaOS zapewnia warstwę odzyskiwania.

Używaj Homarr jako strony startowej, a nie sposobu na obejście panelu administracyjnego

Homarr może centralizować linki i wyświetlać status tylko do odczytu, ale każda aplikacja bazowa nadal ma własne uwierzytelnianie. Nie umieszczaj danych administratora w publicznych widżetach zapewniających dostęp jednym kliknięciem.

Twórz panel warstwami zamiast podłączać wszystko pierwszego dnia

Zacznij od zwykłych linków do ZimaOS, Plex, Home Assistant i innych usług. Gdy sam panel będzie już stabilny, dodawaj po jednej integracji. Dzięki temu łatwo ustalisz, która integracja powoduje zapętlenie logowania, wolne ładowanie strony lub problem z uprawnieniami. Panel z dwudziestoma integracjami API może wyglądać jak jedna uszkodzona aplikacja, nawet gdy tylko jeden backend nie odpowiada.

Używaj wewnętrznych nazw hostów lub stałych adresów IP w sieci LAN

Aktualne instrukcje kontenera Homarr zalecają nazwę hosta lub bezpośredni adres IP, który klienci w Twojej sieci mogą rozpoznawać. Jeśli używasz odwrotnego proxy, zachowaj spójną publiczną nazwę hosta i upewnij się, że żądania WebSocket/API korzystają z tego samego źródła. Unikaj wpisywania na stałe tymczasowych adresów IP Dockera, ponieważ mogą się zmienić po ponownym utworzeniu kontenerów.

Twórz kopię zapasową nie tylko atrakcyjnego układu

Twój panel może zawierać zaszyfrowane dane logowania do integracji, konta użytkowników, ikony i metadane usług. Zachowaj cały trwały /appdata katalog wraz z kluczem szyfrowania. Przetestuj przywracanie do tymczasowego kontenera Homarr, zanim zaczniesz polegać na kopii zapasowej.

Zachowaj ostrożność przy automatycznych aktualizacjach kontenerów

Panel często jest pierwszym miejscem, w którym zauważasz, czy reszta homelabu działa prawidłowo. Jeśli Homarr aktualizuje się automatycznie i jednocześnie ulega awarii inna usługa, diagnozowanie problemu staje się trudniejsze. Przypnij sprawdzoną wersję albo aktualizuj ręcznie, gdy ważna jest dostępność, a następnie przejdź do nowszej wersji po testach.

Po każdej pomyślnej aktualizacji zapisz dokładny tag obrazu Homarr, aby uprościć wycofanie zmian.

FAQ

Czy BigBearCasaOS jest nadal wymagany do korzystania z Homarr?

Nie. Homarr publikuje własną, aktualną ścieżkę instalacji platform Docker i Compose.

Czym jest SECRET_ENCRYPTION_KEY?

To trwały sekret używany przez Homarr do ochrony poufnych danych integracji.

Czy potrzebuję gniazda Dockera?

Tylko w przypadku integracji obsługujących platformę Docker lub elementów sterujących kontenerami.

Czy Homarr może wyświetlać dane systemowe ZimaOS?

Potencjalnie za pośrednictwem niestandardowych integracji korzystających z ZimaOS OpenAPI.

Jak bezpiecznie zaktualizować Homarr?

Zachowaj /appdata, pobierz nowszy obraz, odtwórz usługę i sprawdź panel przed usunięciem starych obrazów.