Kategoria: Jellyfin

Sekcja 1: Wprowadzenie: Upraszczanie Dostępu do Domowego Laboratorium za Pomocą Nginx Proxy Manager na TrueNAS Scale

Współczesne domowe laboratoria (home labs) ewoluowały z prostych konfiguracji do złożonych ekosystemów, w których działają dziesiątki usług, od serwerów multimediów takich jak Plex czy Jellyfin, przez systemy automatyki domowej jak Home Assistant, po osobiste chmury i menedżery haseł. Zarządzanie dostępem do każdej z tych usług, z których każda operuje na unikalnej kombinacji adresu IP i numeru portu, szybko staje się niepraktyczne, niewygodne i, co najważniejsze, niebezpieczne. Ekspozycja wielu portów na świat zewnętrzny zwiększa powierzchnię ataku i komplikuje utrzymanie spójnej polityki bezpieczeństwa.

Rozwiązaniem tego problemu, stosowanym od lat w środowiskach korporacyjnych, jest implementacja centralnej „bramy” lub „pojedynczego punktu wejścia” dla całego ruchu przychodzącego. W terminologii sieciowej rolę tę pełni odwrotne proxy (reverse proxy). Jest to serwer pośredniczący, który odbiera wszystkie żądania od klientów, a następnie, na podstawie nazwy domenowej, kieruje je do odpowiedniej usługi działającej w sieci wewnętrznej. Taka architektura nie tylko upraszcza dostęp, pozwalając na używanie łatwych do zapamiętania adresów (np.

jellyfin.mojadomena.pl zamiast 192.168.1.50:8096), ale także stanowi kluczowy element strategii bezpieczeństwa.

W tym kontekście dwie technologie zyskują na szczególnej popularności wśród entuzjastów: TrueNAS Scale i Nginx Proxy Manager. TrueNAS Scale, bazujący na systemie Debian Linux, przekształcił tradycyjne urządzenie NAS (Network Attached Storage) w potężną, hiperkonwergentną platformę (HCI), zdolną do natywnego uruchamiania aplikacji w kontenerach i maszyn wirtualnych. Z kolei Nginx Proxy Manager (NPM) to narzędzie, które demokratyzuje technologię odwrotnego proxy. Nakłada ono przyjazny dla użytkownika, graficzny interfejs na potężny, ale skomplikowany w konfiguracji serwer Nginx, czyniąc zaawansowane funkcje, takie jak automatyczne zarządzanie certyfikatami SSL, dostępnymi bez konieczności edycji plików konfiguracyjnych z linii poleceń.

Niniejszy artykuł stanowi kompleksowe omówienie procesu wdrożenia Nginx Proxy Manager na platformie TrueNAS Scale. Celem jest nie tylko przedstawienie instrukcji „jak to zrobić”, ale przede wszystkim wyjaśnienie „dlaczego” poszczególne kroki są niezbędne. Analiza rozpocznie się od dogłębnego omówienia obu technologii i ich wzajemnych interakcji. Następnie, przeprowadzony zostanie szczegółowy proces instalacji, z uwzględnieniem specyficznych dla platformy wyzwań i ich rozwiązań, w tym znanego problemu z zawieszaniem się aplikacji w stanie „Deploying”. W dalszej części, na praktycznym przykładzie serwera mediów Jellyfin, zademonstrowana zostanie konfiguracja hosta proxy wraz z zaawansowanymi opcjami bezpieczeństwa. Raport zakończy się podsumowaniem korzyści i wskazaniem dalszych kroków w celu pełnego wykorzystania potencjału tego potężnego duetu.

Sekcja 2: Analiza Narzędzi: Nginx Proxy Manager i Ekosystem Aplikacji TrueNAS Scale

Zrozumienie fundamentalnych zasad działania Nginx Proxy Manager oraz architektury, w której jest on wdrażany – czyli systemu aplikacji TrueNAS Scale – jest kluczowe dla pomyślnej instalacji, efektywnej konfiguracji i, co najważniejsze, skutecznego diagnozowania ewentualnych problemów. Te dwa komponenty, choć zaprojektowane do współpracy, posiadają własną, unikalną specyfikę, której ignorowanie jest najczęstszą przyczyną niepowodzeń.

Podsekcja 2.1: Zrozumieć Nginx Proxy Manager (NPM)

U podstaw funkcjonalności NPM leży koncepcja odwrotnego proxy, która jest fundamentalna dla nowoczesnej architektury sieciowej. Zrozumienie jej działania pozwala docenić wartość, jaką wnosi NPM.

Definicja i Funkcje Odwrotnego Proxy

Odwrotne proxy to serwer, który działa jako pośrednik po stronie serwera. W przeciwieństwie do tradycyjnego (forward) proxy, które działa w imieniu klienta, odwrotne proxy działa w imieniu serwera (lub grupy serwerów). Odbiera ono żądania od klientów z Internetu i przekazuje je do odpowiednich serwerów w sieci lokalnej, które faktycznie przechowują treść. Dla klienta zewnętrznego odwrotne proxy jest jedynym widocznym punktem kontaktowym; wewnętrzna struktura sieci pozostaje ukryta.

Kluczowe korzyści płynące z tego rozwiązania to:

• Bezpieczeństwo: Ukrywanie topologii sieci wewnętrznej i rzeczywistych adresów IP serwerów aplikacyjnych znacząco utrudnia bezpośrednie ataki na te usługi.
• Centralizacja zarządzania SSL/TLS (SSL Termination): Zamiast konfigurować certyfikaty SSL na każdym z kilkunastu serwerów aplikacyjnych, można zarządzać nimi w jednym miejscu – na odwrotnym proxy. Szyfrowanie i deszyfrowanie ruchu (SSL Termination) odbywa się na serwerze proxy, co odciąża serwery backendowe.
• Równoważenie obciążenia (Load Balancing): W bardziej zaawansowanych scenariuszach, odwrotne proxy może rozdzielać ruch pomiędzy wiele identycznych serwerów aplikacyjnych, zapewniając wysoką dostępność i skalowalność usługi.
• Uproszczony dostęp: Umożliwia dostęp do wielu usług za pośrednictwem standardowych portów 80 (HTTP) i 443 (HTTPS) przy użyciu różnych subdomen, eliminując potrzebę zapamiętywania i otwierania wielu portów.

NPM jako Warstwa Zarządzania

Należy podkreślić, że Nginx Proxy Manager nie jest nowym, konkurencyjnym dla Nginx serwerem WWW. Jest to aplikacja zarządzająca, zbudowana na bazie otwartego kodu źródłowego Nginx, która pełni rolę graficznej nakładki (GUI) na jego funkcje odwrotnego proxy. Zamiast ręcznie edytować złożone pliki konfiguracyjne Nginx, użytkownik może wykonywać te same operacje za pomocą kilku kliknięć w intuicyjnym interfejsie webowym.

Główne cechy, które przyczyniły się do popularności NPM, to:

• Graficzny interfejs użytkownika: Oparty na frameworku Tabler, interfejs jest przejrzysty i łatwy w obsłudze, co drastycznie obniża próg wejścia dla użytkowników niebędących ekspertami od Nginx.
• Automatyzacja SSL: Wbudowana integracja z Let’s Encrypt pozwala na automatyczne, darmowe generowanie certyfikatów SSL oraz ich cykliczne odnawianie. To jedna z najważniejszych i najbardziej docenianych funkcji.
• Wdrożenie oparte na Dockerze: NPM jest dystrybuowany jako gotowy do użycia obraz Docker, co sprawia, że jego instalacja na dowolnej platformie wspierającej kontenery jest niezwykle prosta.
• Zarządzanie dostępem: Narzędzie oferuje funkcje tworzenia list kontroli dostępu (Access Control Lists, ACL) oraz zarządzania użytkownikami z różnymi poziomami uprawnień, co pozwala na granularne kontrolowanie dostępu do poszczególnych usług.

Porównanie: NPM vs. Tradycyjny Nginx

Wybór między Nginx Proxy Manager a ręczną konfiguracją Nginx to klasyczny kompromis między prostotą a elastycznością. Poniższa tabela zestawia kluczowe różnice między tymi dwoma podejściami.

Tabela 1: Nginx Proxy Manager vs. Tradycyjny Nginx

Tabela ta jasno pokazuje, że NPM jest narzędziem strategicznie dopasowanym do potrzeb docelowej publiczności – entuzjastów domowych laboratoriów. Użytkownicy ci świadomie rezygnują z części zaawansowanej elastyczności na rzecz ogromnych korzyści w postaci prostoty obsługi i szybkości wdrożenia.

Podsekcja 2.2: Architektura Aplikacji w TrueNAS Scale

Aby zrozumieć, dlaczego instalacja NPM na TrueNAS Scale może napotkać specyficzne problemy, konieczne jest poznanie sposobu, w jaki ta platforma zarządza aplikacjami. Nie jest to bowiem typowe środowisko Docker.

Fundamenty: Linux i Hiperkonwergencja

Kluczową zmianą architektoniczną w TrueNAS Scale w stosunku do jego poprzednika, TrueNAS CORE, było przejście z systemu operacyjnego FreeBSD na Debiana, dystrybucję Linuksa. Ta decyzja otworzyła drzwi do natywnego wsparcia dla technologii, które zdominowały świat chmury i konteneryzacji, przede wszystkim dla kontenerów Docker i wirtualizacji opartej na KVM. Dzięki temu TrueNAS Scale stał się platformą hiperkonwergentną, łączącą w sobie funkcje pamięci masowej, obliczeń i wirtualizacji.

System Aplikacji

Aplikacje są dystrybuowane za pośrednictwem katalogów (Catalogs), które działają na zasadzie repozytoriów. Te katalogi są z kolei podzielone na tzw. „trainy” (pociągi), które określają stabilność i źródło aplikacji:

• stable: Domyślny „train” dla oficjalnych, przetestowanych przez iXsystems aplikacji.
• enterprise: Aplikacje zweryfikowane pod kątem zastosowań biznesowych.
• community: Aplikacje tworzone i utrzymywane przez społeczność. To tutaj domyślnie znajduje się Nginx Proxy Manager.
• test: Aplikacje w fazie deweloperskiej.

Przynależność NPM do katalogu community oznacza, że choć jest on łatwo dostępny, jego wsparcie techniczne opiera się na społeczności, a nie bezpośrednio na producencie TrueNAS.

Zarządzanie Pamięcią Masową dla Aplikacji

Zanim jakakolwiek aplikacja zostanie zainstalowana, TrueNAS Scale wymaga od użytkownika wskazania puli ZFS, która będzie dedykowana do przechowywania danych aplikacji. Kiedy aplikacja jest instalowana, jej dane (konfiguracja, bazy danych itp.) muszą być gdzieś zapisane w sposób trwały. TrueNAS Scale oferuje tu kilka opcji, ale domyślną i rekomendowaną dla prostoty jest

ixVolume.

ixVolume to specjalny typ woluminu, który automatycznie tworzy dedykowany, zarządzany przez system zbiór danych (ZFS dataset) wewnątrz wybranej puli aplikacji. Ten zbiór danych jest odizolowany, a system nadaje mu bardzo specyficzne uprawnienia. Domyślnie, właścicielem tego zbioru danych staje się użytkownik systemowy

apps o identyfikatorze (UID) 568 i grupie (GID) 568. Kontener uruchomionej aplikacji również działa z uprawnieniami tego właśnie użytkownika.

To jest sedno problemu. Standardowy obraz Docker dla Nginx Proxy Manager zawiera skrypty startowe (np. te pochodzące z Certbota, narzędzia do obsługi certyfikatów), które przy pierwszym uruchomieniu próbują zmienić właściciela (chown) katalogów z danymi, takich jak /data czy /etc/letsencrypt, aby upewnić się, że mają do nich odpowiednie uprawnienia. Kiedy kontener NPM startuje wewnątrz sandboksowego środowiska aplikacji TrueNAS, jego skrypt startowy, działając jako nieuprzywilejowany użytkownik apps (UID 568), próbuje wykonać operację chown na woluminie ixVolume. Operacja ta kończy się niepowodzeniem, ponieważ użytkownik apps nie jest właścicielem nadrzędnych katalogów i nie ma uprawnień do zmiany właściciela plików na woluminie zarządzanym przez K3s. Ten błąd uprawnień powoduje, że skrypt startowy kontenera zatrzymuje się, a sam kontener nigdy nie osiąga stanu „uruchomiony”, co w interfejsie TrueNAS Scale objawia się jako niekończący się stan „Deploying”.

Sekcja 3: Instalacja i Konfiguracja Nginx Proxy Manager na TrueNAS Scale

Proces instalacji Nginx Proxy Manager na TrueNAS Scale jest prosty, pod warunkiem zwrócenia uwagi na kilka kluczowych parametrów konfiguracyjnych, które są często źródłem problemów. Poniższa instrukcja krok po kroku przeprowadzi przez ten proces, podkreślając krytyczne decyzje, które należy podjąć.

Krok 1: Przygotowanie TrueNAS Scale

Przed przystąpieniem do instalacji jakiejkolwiek aplikacji, należy upewnić się, że usługa aplikacji w TrueNAS Scale jest poprawnie skonfigurowana.

1. Należy zalogować się do interfejsu webowego TrueNAS Scale.
2. Przejść do sekcji Apps.
3. Jeśli usługa nie jest jeszcze skonfigurowana, system wyświetli monit o wybranie puli ZFS, która będzie używana do przechowywania danych wszystkich aplikacji. Należy wybrać odpowiednią pulę i zapisać ustawienia. Po chwili status usługi powinien zmienić się na „Running”.

Krok 2: Znalezienie Aplikacji

Nginx Proxy Manager jest dostępny w oficjalnym katalogu społecznościowym.

1. W sekcji Apps należy przejść do zakładki Discover.
2. W polu wyszukiwania wpisać nginx-proxy-manager.
3. W wynikach powinna pojawić się aplikacja. Należy upewnić się, że pochodzi z katalogu community.
4. Kliknąć przycisk Install, aby przejść do ekranu konfiguracji.

Krok 3: Kluczowe Parametry Konfiguracji

Ekran instalacji przedstawia wiele opcji. Większość z nich można pozostawić z domyślnymi wartościami, jednak kilka sekcji wymaga szczególnej uwagi.

Application Name

W polu Application Name należy wpisać nazwę dla instalacji, na przykład nginx-proxy-manager. Nazwa ta będzie używana do identyfikacji aplikacji w systemie.

Network Configuration (Konfiguracja Sieci)

To jest najważniejszy i najbardziej problematyczny etap konfiguracji. Domyślnie, interfejs zarządzania TrueNAS Scale używa standardowych portów webowych: 80 dla HTTP i 443 dla HTTPS. Ponieważ Nginx Proxy Manager, aby działać jako brama dla całego ruchu webowego, również powinien nasłuchiwać na tych portach, dochodzi do bezpośredniego konfliktu. Istnieją dwie główne strategie rozwiązania tego problemu, każda z własnym zestawem kompromisów.

• Strategia A (Rekomendowana): Zmiana portów TrueNAS ScaleTa metoda jest uważana za „najczystszą” z perspektywy NPM, ponieważ pozwala mu działać w sposób, do jakiego został zaprojektowany.
  1. Należy anulować instalację NPM i przejść do System Settings -> General.W sekcji GUI SSL/TLS Certificate, zmienić Web Interface HTTP Port na niestandardowy, np. 880, oraz Web Interface HTTPS Port na np. 8443.Zapisać zmiany. Od tego momentu dostęp do interfejsu TrueNAS Scale będzie możliwy pod adresem http://<adres-ip-truenas>:880 lub https://<adres-ip-truenas>:8443.Powrócić do instalacji NPM i w sekcji Network Configuration przypisać HTTP Port do 80 i HTTPS Port do 443.
  • Zalety: NPM działa na standardowych portach, co upraszcza konfigurację i eliminuje potrzebę translacji portów na routerze.
  • Wady: Zmienia fundamentalny sposób dostępu do samego NAS-a. W rzadkich przypadkach, jak odnotowano na forach, może to powodować nieprzewidziane skutki uboczne, takie jak problemy z połączeniami SSH między systemami TrueNAS.
• Strategia B (Alternatywna): Użycie wysokich portów dla NPMTa metoda jest mniej inwazyjna dla konfiguracji samego TrueNAS, ale przenosi złożoność na poziom routera.
  1. W konfiguracji NPM, w sekcji Network Configuration, należy pozostawić porty TrueNAS bez zmian i przypisać NPM wysokie, nieużywane porty, np. 30080 dla HTTP i 30443 dla HTTPS. TrueNAS Scale rezerwuje porty poniżej 9000 dla systemu, więc należy wybrać wartości powyżej tego progu.Po zainstalowaniu NPM, należy skonfigurować przekierowanie portów (port forwarding) na routerze brzegowym, tak aby ruch przychodzący z internetu na port 80 był kierowany na port 30080 adresu IP TrueNAS, a ruch z portu 443 na port 30443.
  • Zalety: Konfiguracja TrueNAS Scale pozostaje nienaruszona.
  • Wady: Wymaga dodatkowej konfiguracji na routerze. Każda usługa proxy będzie wymagała jawnego przekierowania, co może być mylące.

Idealnym rozwiązaniem byłoby przypisanie NPM dedykowanego adresu IP w sieci lokalnej (np. za pomocą technologii macvlan), co całkowicie wyeliminowałoby konflikt portów. Niestety, interfejs graficzny instalatora aplikacji w TrueNAS Scale nie udostępnia tej opcji w prosty sposób.

Storage Configuration (Konfiguracja Pamięci)

Aby zapewnić, że konfiguracja NPM, w tym utworzone hosty proxy i certyfikaty SSL, przetrwa aktualizacje lub ponowne wdrożenie aplikacji, należy skonfigurować trwałą pamięć masową.

1. W sekcji Storage Configuration należy skonfigurować dwa woluminy.
2. Dla Nginx Proxy Manager Data Storage (ścieżka /data) oraz Nginx Proxy Manager Certs Storage (ścieżka /etc/letsencrypt), należy wybrać typ ixVolume.
3. Pozostawienie tych ustawień zapewni, że TrueNAS utworzy dedykowane zbiory danych ZFS dla konfiguracji i certyfikatów, które będą niezależne od samego kontenera aplikacji.

Krok 4: Pierwsze Uruchomienie i Zabezpieczenie

Po skonfigurowaniu powyższych parametrów (i ewentualnym zastosowaniu poprawek z Sekcji 4), należy kliknąć Install. Po kilku chwilach aplikacja powinna przejść w stan „Running”.

1. Dostęp do interfejsu NPM jest możliwy pod adresem http://<adres-ip-truenas>:PORT, gdzie PORT to port WebUI skonfigurowany podczas instalacji (domyślnie 81 wewnątrz kontenera, ale mapowany na wyższy port, np. 30020, jeśli nie zmieniono portów TrueNAS).
2. Domyślne poświadczenia logowania to:
   • Email: admin@example.com
   • Password: changeme
3. Po pierwszym zalogowaniu system natychmiast poprosi o zmianę tych danych. Jest to absolutnie kluczowy krok bezpieczeństwa i należy go wykonać niezwłocznie.

Sekcja 4: Rozwiązywanie Problemu „Deploying”: Diagnostyka i Naprawa Błędów Instalacji

Jednym z najczęściej napotykanych i najbardziej frustrujących problemów podczas wdrażania Nginx Proxy Manager na TrueNAS Scale jest sytuacja, w której aplikacja po instalacji na stałe zawiesza się w stanie „Deploying”. Użytkownik czeka, odświeża stronę, ale status nigdy nie zmienia się na „Running”. Podgląd logów kontenera często nie dostarcza jednoznacznej odpowiedzi. Ten problem nie jest błędem samego NPM, lecz, jak zdiagnozowano wcześniej, symptomem fundamentalnego konfliktu uprawnień między generycznym kontenerem a specyficznym, zabezpieczonym środowiskiem w TrueNAS Scale.

Opis Problemu i Główna Przyczyna

Po kliknięciu przycisku „Install” w kreatorze aplikacji, TrueNAS Scale rozpoczyna proces wdrażania. W tle pobierany jest obraz Docker, tworzone są woluminy ixVolume i uruchamiany jest kontener z zadaną konfiguracją. Skrypt startowy wewnątrz kontenera NPM próbuje wykonać operacje konserwacyjne, w tym zmianę właściciela kluczowych katalogów. Ponieważ kontener działa jako użytkownik o ograniczonych uprawnieniach (apps, UID 568) na systemie plików, którego nie kontroluje w pełni, operacja ta kończy się niepowodzeniem. Skrypt zatrzymuje swoje działanie, a kontener nigdy nie sygnalizuje systemowi, że jest gotowy do pracy. W rezultacie, z perspektywy interfejsu TrueNAS, aplikacja na zawsze pozostaje w fazie wdrażania.

Na szczęście, dzięki pracy społeczności i deweloperów, istnieją sprawdzone i skuteczne rozwiązania tego problemu. Co ciekawe, ewolucja tych rozwiązań doskonale ilustruje dynamikę rozwoju oprogramowania open-source.

Rozwiązanie 1: Użycie Zmiennej Środowiskowej (Metoda Rekomendowana)

Jest to nowoczesne, precyzyjne i najbezpieczniejsze rozwiązanie problemu. Zostało ono wprowadzone przez twórców kontenera NPM właśnie w odpowiedzi na problemy zgłaszane przez użytkowników platform takich jak TrueNAS Scale. Zamiast eskalować uprawnienia, instruuje się kontener, aby pominął problematyczny krok.

Aby zaimplementować to rozwiązanie, należy:

1. Podczas instalacji aplikacji (lub podczas jej edycji, jeśli już została utworzona i zawisła), należy przejść do sekcji Application Configuration.
2. Znaleźć podsekcję Nginx Proxy Manager Configuration i kliknąć Add przy Additional Environment Variables.
3. Skonfigurować nową zmienną środowiskową w następujący sposób:
   • Variable Name: SKIP_CERTBOT_OWNERSHIP
   • Variable Value: true
4. Zapisać konfigurację i zainstalować lub zaktualizować aplikację.

Dodanie tej flagi informuje skrypt startowy Certbota wewnątrz kontenera, że ma on pominąć krok chown (zmiany właściciela) dla swoich plików konfiguracyjnych. Skrypt przechodzi dalej, kontener poprawnie się uruchamia i zgłasza gotowość, a aplikacja przechodzi w stan „Running”. Jest to metoda zalecana dla wszystkich nowszych wersji TrueNAS Scale (Electric Eel, Dragonfish i nowszych).

Rozwiązanie 2: Zmiana Użytkownika na Root (Metoda Historyczna)

To rozwiązanie było pierwszym, które odkryła społeczność. Jest to bardziej „brutalna” metoda, która rozwiązuje problem przez nadanie kontenerowi pełnych uprawnień. Choć skuteczna, jest uważana za mniej elegancką i potencjalnie mniej bezpieczną z perspektywy zasady minimalnych uprawnień.

Aby zaimplementować to rozwiązanie, należy:

1. Podczas instalacji lub edycji aplikacji, należy przejść do sekcji User and Group Configuration.
2. Zmienić wartość w polu User ID z domyślnej 568 na 0.
3. Pozostawić Group ID bez zmian lub również ustawić na 0.
4. Zapisać konfigurację i wdrożyć aplikację.

Ustawienie User ID na 0 powoduje, że proces wewnątrz kontenera jest uruchamiany z uprawnieniami użytkownika root. Użytkownik root ma nieograniczone uprawnienia, więc problematyczna operacja chown wykonuje się bezbłędnie, a kontener startuje poprawnie. Ta metoda była szczególnie potrzebna w starszych wersjach TrueNAS Scale (np. Dragonfish) i jest udokumentowana jako działające obejście. Chociaż nadal działa, metoda ze zmienną środowiskową jest preferowana, ponieważ nie wymaga eskalacji uprawnień dla całego kontenera.

Weryfikacja

Niezależnie od wybranej metody, po zapisaniu zmian i ponownym wdrożeniu aplikacji, należy obserwować jej status w zakładce Apps -> Installed. Po krótkiej chwili status powinien zmienić się z „Deploying” na „Running”, co oznacza, że problem został pomyślnie rozwiązany i Nginx Proxy Manager jest gotowy do konfiguracji.

Sekcja 5: Praktyczne Zastosowanie: Zabezpieczanie Serwera Mediów Jellyfin

Teoria i poprawna instalacja to dopiero początek. Prawdziwa moc Nginx Proxy Manager ujawnia się w praktyce, gdy zaczynamy go używać do zarządzania dostępem do naszych usług. Jellyfin, popularny, darmowy serwer multimediów, jest doskonałym przykładem do zademonstrowania tego procesu, ponieważ jego pełna funkcjonalność zależy od jednego, często pomijanego ustawienia w konfiguracji proxy. Poniższy przewodnik zakłada, że Jellyfin jest już zainstalowany i działa w sieci lokalnej, dostępny pod adresem IP:PORT (np. 192.168.1.10:8096).

Krok 1: Konfiguracja DNS

Zanim NPM będzie mógł kierować ruch, świat zewnętrzny musi wiedzieć, gdzie go wysłać.

1. Należy zalogować się do panelu zarządzania swoją domeną internetową (np. u rejestratora domeny lub dostawcy DNS, jak Cloudflare).
2. Utworzyć nowy rekord DNS typu A.
3. W polu Name (lub Host) należy wpisać subdomenę, która będzie używana do dostępu do Jellyfin (np. jellyfin).
4. W polu Value (lub Points to) należy wpisać publiczny adres IP swojej sieci domowej (routera).

Krok 2: Uzyskanie Certyfikatu SSL w NPM

Zabezpieczenie połączenia za pomocą HTTPS jest kluczowe. NPM sprawia, że ten proces jest trywialny, zwłaszcza przy użyciu metody DNS Challenge, która jest bezpieczniejsza, ponieważ nie wymaga otwierania żadnych portów na routerze.

1. W interfejsie NPM należy przejść do SSL Certificates i kliknąć Add SSL Certificate, a następnie wybrać Let's Encrypt.
2. W polu Domain Names należy wpisać swoją subdomenę, np. jellyfin.twojadomena.com. Można również od razu wygenerować certyfikat typu „wildcard” (np. *.twojadomena.com), który będzie pasował do wszystkich subdomen.
3. Należy włączyć opcję Use a DNS Challenge.
4. Z listy DNS Provider można wybrać swojego dostawcę DNS (np. Cloudflare).
5. W polu Credentials File Content należy wkleić token API uzyskany od dostawcy DNS. W przypadku Cloudflare, należy wygenerować token z uprawnieniami do edycji strefy DNS (Zone:DNS:Edit).
6. Należy zaakceptować warunki usługi Let’s Encrypt i zapisać formularz. Po chwili NPM użyje API do tymczasowego dodania rekordu TXT w DNS, co udowodni Let’s Encrypt, że jesteśmy właścicielami domeny. Certyfikat zostanie wygenerowany i zapisany.

Krok 3: Tworzenie Hosta Proxy (Proxy Host)

To jest serce konfiguracji, gdzie łączymy domenę, certyfikat i wewnętrzną usługę.

1. W NPM należy przejść do Hosts -> Proxy Hosts i kliknąć Add Proxy Host.
2. Otworzy się formularz z kilkoma zakładkami.

Zakładka „Details”

• Domain Names: Należy wpisać pełną nazwę domenową, która została skonfigurowana w DNS, np. jellyfin.twojadomena.com.
• Scheme: Należy wybrać http, ponieważ komunikacja między NPM a Jellyfin w sieci lokalnej zazwyczaj nie jest szyfrowana.
• Forward Hostname / IP: Należy wpisać lokalny adres IP serwera, na którym działa Jellyfin, np. 192.168.1.10.
• Forward Port: Należy wpisać port, na którym nasłuchuje Jellyfin, np. 8096.
• Websocket Support: To jest absolutnie krytyczne ustawienie. Należy zaznaczyć tę opcję. Jellyfin intensywnie korzysta z technologii WebSocket do komunikacji w czasie rzeczywistym, np. do aktualizacji statusu odtwarzania na pulpicie nawigacyjnym (dashboard) czy do działania funkcji Syncplay. Bez włączonego wsparcia dla WebSocket, strona główna Jellyfin załaduje się poprawnie, ale wiele kluczowych funkcji nie będzie działać, co prowadzi do trudnych do zdiagnozowania problemów.

Zakładka „SSL”

• SSL Certificate: Z rozwijanej listy należy wybrać certyfikat wygenerowany w poprzednim kroku dla domeny Jellyfin.
• Force SSL: Należy włączyć tę opcję, aby wszystkie połączenia HTTP były automatycznie przekierowywane na bezpieczny HTTPS.
• HTTP/2 Support: Włączenie tej opcji może poprawić wydajność ładowania strony.

Po skonfigurowaniu obu zakładek należy zapisać hosta proxy.

Krok 4: Testowanie

Po zapisaniu konfiguracji, Nginx w tle przeładuje swoje ustawienia. Teraz powinno być możliwe otwarcie przeglądarki i wpisanie adresu https://jellyfin.twojadomena.com. Użytkownik powinien zobaczyć stronę logowania Jellyfin, a połączenie powinno być zabezpieczone certyfikatem SSL (widoczna kłódka w pasku adresu).

Podsekcja 5.1: Zaawansowane Wzmacnianie Bezpieczeństwa (Opcjonalne)

Domyślna konfiguracja jest w pełni funkcjonalna, ale dla zwiększenia bezpieczeństwa można dodać dodatkowe nagłówki HTTP, które instruują przeglądarkę, jak ma się zachowywać. W tym celu należy edytować utworzonego hosta proxy i przejść do zakładki Advanced. W polu Custom Nginx Configuration można wkleić dodatkowe dyrektywy.

Warto zauważyć, że NPM ma pewne dziwactwo: dyrektywy add_header dodane bezpośrednio w tym polu mogą nie zostać zastosowane. Bezpieczniejszym podejściem jest utworzenie niestandardowej lokalizacji (Custom Location) dla ścieżki / i wklejenie nagłówków w jej polu konfiguracyjnym.

Poniższa tabela przedstawia rekomendowane nagłówki bezpieczeństwa.

Tabela 2: Rekomendowane Nagłówki Bezpieczeństwa dla Jellyfin w NPM

Zastosowanie tych nagłówków stanowi dodatkową warstwę obrony i jest uznawane za dobrą praktykę w zabezpieczaniu aplikacji webowych. Krytyczne jest jednak, aby korzystać z aktualnych rekomendacji, jak w przypadku X-XSS-Protection, którego ślepe kopiowanie ze starszych poradników mogłoby osłabić bezpieczeństwo.

Sekcja 6: Wnioski i Dalsze Kroki

Połączenie Nginx Proxy Manager z platformą TrueNAS Scale tworzy niezwykle potężne i elastyczne środowisko do zarządzania domowym laboratorium. Jak wykazano w niniejszym raporcie, ta synergia pozwala na centralizację zarządzania dostępem, drastyczne uproszczenie wdrożenia i utrzymania zabezpieczeń SSL/TLS oraz profesjonalizację sposobu, w jaki użytkownicy wchodzą w interakcję ze swoimi samo-hostowanymi usługami. Kluczem do sukcesu jest jednak nie tylko ślepe podążanie za instrukcjami, ale przede wszystkim zrozumienie fundamentalnych zasad działania obu technologii. Świadomość, że aplikacje w TrueNAS Scale działają w ramach restrykcyjnego ekosystemu, jest niezbędna do skutecznego diagnozowania i rozwiązywania specyficznych problemów, takich jak błąd zawieszania się w stanie „Deploying”.

Podsumowanie Strategicznych Korzyści

Wdrożenie NPM na TrueNAS Scale przynosi wymierne korzyści:

• Centralizacja i prostota: Wszystkie przychodzące żądania są zarządzane z jednego, intuicyjnego panelu, co eliminuje chaos związany z wieloma adresami IP i portami.
• Wzmocnione bezpieczeństwo: Automatyzacja certyfikatów SSL, ukrywanie wewnętrznej topologii sieci oraz możliwość implementacji zaawansowanych nagłówków bezpieczeństwa tworzą solidną pierwszą linię obrony.
• Profesjonalny wizerunek i wygoda: Używanie łatwych do zapamiętania, spersonalizowanych subdomen (np. media.mojadomena.pl) zamiast technicznych adresów IP znacząco poprawia komfort użytkowania.

Rekomendacje i Dalsze Kroki

Po pomyślnym wdrożeniu Nginx Proxy Manager i zabezpieczeniu pierwszej aplikacji, warto zbadać jego dalsze możliwości, aby w pełni wykorzystać potencjał narzędzia.

• Eksploracja List Dostępu (Access Lists): NPM pozwala na tworzenie list kontroli dostępu (ACL), które mogą ograniczać dostęp do określonych hostów proxy na podstawie adresu IP źródłowego. Jest to niezwykle użyteczna funkcja do zabezpieczania paneli administracyjnych. Można na przykład stworzyć regułę, która zezwala na dostęp do interfejsu TrueNAS Scale lub panelu samego NPM tylko z adresów IP w sieci lokalnej, blokując wszelkie próby dostępu z zewnątrz.
• Strategia Kopii Zapasowych: Konfiguracja Nginx Proxy Manager, przechowywana w woluminie ixVolume, jest krytycznym zasobem. Jej utrata oznaczałaby konieczność ponownego konfigurowania wszystkich hostów proxy i certyfikatów. TrueNAS Scale oferuje wbudowane narzędzia do automatyzacji tworzenia kopii zapasowych. Należy skonfigurować zadanie Periodic Snapshot Task dla zbioru danych (dataset) zawierającego dane aplikacji NPM (ix-applications/releases/nginx-proxy-manager), aby regularnie tworzyć migawki jego stanu.
• Zabezpieczanie Innych Aplikacji: Wiedza zdobyta podczas konfiguracji Jellyfin jest uniwersalna. Można ją teraz zastosować do zabezpieczenia praktycznie każdej innej usługi webowej działającej w domowym laboratorium, takiej jak Home Assistant, serwer plików, osobisty menedżer haseł (np. Vaultwarden, będący implementacją Bitwarden) czy system blokowania reklam AdGuard Home. Należy pamiętać, aby dla każdej aplikacji wymagającej komunikacji w czasie rzeczywistym włączyć opcję Websocket Support.
• Monitorowanie i Diagnostyka: Interfejs NPM udostępnia dzienniki dostępu (access logs) i błędów (error logs) dla każdego hosta proxy. Regularne przeglądanie tych logów może pomóc w diagnozowaniu problemów z dostępem, identyfikowaniu prób nieautoryzowanych połączeń oraz optymalizacji konfiguracji.

Opanowanie Nginx Proxy Manager na TrueNAS Scale to inwestycja, która zwraca się wielokrotnie w postaci zwiększonego bezpieczeństwa, wygody i kontroli nad cyfrowym ekosystemem. Jest to kolejny krok na drodze od prostego użytkownika do świadomego architekta własnej, domowej infrastruktury.