Instalacja

Uruchom HolyArrs w Dockerze i otwórz go w przeglądarce. Zajmie to kilka minut.

Zanim zaczniesz

• Komputer z Dockerem i Docker Compose.
• Twoje foldery z multimediami albo miejsce, w którym je utworzysz. Jeśli chcesz, żeby pliki były przenoszone od razu, a nie kopiowane, najpierw przeczytaj Foldery.
• Na NAS-ie, Unraidzie lub Synology zajrzyj do NAS, Synology i Unraid. Bez Dockera zobacz Archiwa przenośne.

Kroki

1. Utwórz folder na konfigurację na dysku lokalnym, na przykład /srv/holyarrs/config. Nie na udziale sieciowym. W Docker Desktop użyj zamiast tego nazwanego volume (wolumenu). Zobacz Docker Desktop.

2. Sprawdź, do jakiego użytkownika i grupy należą twoje foldery z multimediami:

   id youruser
   # uid=1000(youruser) gid=1000(youruser)

   Użyj uid jako PUID, a gid jako PGID.

3. Zapisz to jako docker-compose.yml i zmień ścieżki:

   name: HolyArrs
   services:
     holyarrs:
       image: holyarrs/holyarrs:latest
       container_name: holyarrs
       environment:
         - PUID=1000
         - PGID=1000
         - TZ=Etc/UTC
       volumes:
         - /srv/holyarrs/config:/config
         - /path/to/movies:/movies #optional
         - /path/to/tv:/tv #optional
         - /path/to/music:/music #optional
         - /path/to/downloads:/downloads #optional
       ports:
         - 6262:6262
       restart: unless-stopped

4. Uruchom:

   docker compose up -d
   docker compose ps

   Gdy HolyArrs zacznie odpowiadać, kontener pokaże się jako healthy.

5. Otwórz http://your-server:6262 i od razu utwórz konto właściciela. Nie ma hasła domyślnego. Dopóki go nie utworzysz, właścicielem zostaje ten, kto pierwszy otworzy HolyArrs.

6. Przejdź przez konfigurację, która otworzy się dalej. Zobacz Pierwsze uruchomienie.

Uwaga

Nie ma hasła domyślnego. Właścicielem nowego HolyArrs zostaje ten, kto otworzy go pierwszy. Utwórz konto teraz.

Jeśli wolisz docker run:

docker run -d \
  --name=holyarrs \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -p 6262:6262 \
  -v /srv/holyarrs/config:/config \
  -v /path/to/movies:/movies `#optional`   -v /path/to/tv:/tv `#optional`   -v /path/to/music:/music `#optional`   -v /path/to/downloads:/downloads `#optional` \
  --restart unless-stopped \
  holyarrs/holyarrs:latest

Tag image’a

Tag	Co dostajesz
latest	Najnowsza wersja
1.0.2 (dowolna wersja)	Dokładnie ta wersja, która nigdy się nie zmienia

Opis ustawień

Porty i foldery

Ustawienie	Co robi
-p 6262:6262	Aplikacja webowa.
-v /config	Bazy danych, ustawienia, klucz główny, backupy i logi. Tylko dysk lokalny.
-v /movies	Opcjonalnie. Folder biblioteki z filmami.
-v /tv	Opcjonalnie. Folder biblioteki z serialami.
-v /music	Opcjonalnie. Folder biblioteki z muzyką.
-v /downloads	Opcjonalnie. Folder, do którego Downloader pobiera pliki. Zobacz Foldery multimediów.
--read-only=true	Opcjonalnie. Zobacz Główny system plików tylko do odczytu.
--user=1000:1000	Opcjonalnie. Zobacz Uruchomienie jako stały użytkownik.

Zmienne środowiskowe

Zmienna	Co robi
PUID, PGID	Użytkownik i grupa, z którymi działa HolyArrs. Gdy je pominiesz, to 1000 i 1000.
TZ	Strefa czasowa, na przykład Europe/Amsterdam.
UMASK	Opcjonalnie. Które bity uprawnień nowe pliki pomijają, na przykład 022 lub 002.
HOLYARRS_SAVE_PATH	Opcjonalnie. Folder zapisu Downloadera, taki, jaki widzi Downloader.
HOLYARRS_ALLOWED_HOSTS	Opcjonalnie. Dodatkowe nazwy hostów, pod którymi ludzie łączą się z HolyArrs, rozdzielone przecinkami.
HOLYARRS_TRUSTED_PROXIES	Opcjonalnie. Adres lub sieć twojego reverse proxy.
HOLYARRS_URL_BASE	Opcjonalnie. Udostępnij HolyArrs pod ścieżką. Zobacz URL base i reverse proxy.
HOLYARRS_MASTER_KEY_FILE	Opcjonalnie. Wczytaj klucz główny z osobnego pliku.

Każda zmienna może pochodzić z pliku. Dopisz FILE__ przed nazwą, a jako wartość podaj ścieżkę do pliku:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

HolyArrs pomija jeden znak nowej linii na końcu pliku. Działa to także dla PUID, PGID, UMASK i TZ. Jeśli pliku brakuje, HolyArrs się zatrzymuje i podaje nazwę zmiennej w logu. Nigdy nie wypisuje wartości.

Image

Image zawiera HolyArrs i prawie nic poza tym. Nie ma shella, więc nie wejdziesz do niego przez docker exec, żeby się rozejrzeć. Zamiast tego przeczytaj log przez docker logs holyarrs albo otwórz logs/holyarrs.log w folderze konfiguracji.

Własne polecenia HolyArrs nadal działają przez docker exec:

docker exec holyarrs /holyarrs doctor
docker exec -i holyarrs /holyarrs reset-owner
docker exec holyarrs /holyarrs restore --pre-update

Image’y są budowane dla amd64, 64-bitowego ARM i 32-bitowego ARM. Na komputerze z około 2.5 GiB pamięci RAM lub mniej HolyArrs sam włącza tryb niskiego zużycia pamięci. Mówi o tym pierwsza linia logu.

Użytkownik i grupa

Kontener startuje jako root tylko po to, żeby się skonfigurować. W razie potrzeby przekazuje folder konfiguracji użytkownikowi PUID:PGID, a potem na stałe przełącza się na tego użytkownika. Pierwsza linia logu pokazuje użytkownika, grupę i umask.

HolyArrs nigdy nie zmienia właściciela twoich folderów z multimediami ani z pobranymi plikami. Nadaj użytkownikowi PUID dostęp do zapisu w tych folderach samodzielnie. Sam odczyt nie wystarczy, bo HolyArrs tworzy foldery i przenosi pliki.

Niektóre systemy przechowywania nie pozwalają zmieniać właściciela, na przykład NFS z root squash, SMB albo punkt montowania tylko do odczytu. HolyArrs zapisuje wtedy ostrzeżenie w logu i działa dalej. Ustaw ręcznie uprawnienia tak, żeby folder konfiguracji był zapisywalny dla PUID:PGID.

Zmiana użytkownika wymaga uprawnień (capabilities) CHOWN, DAC_OVERRIDE, SETUID i SETGID. Docker nadaje je domyślnie. Jeśli je odbierzesz, HolyArrs zatrzyma się z komunikatem. Nie wraca do roota. Żeby naprawdę działać jako root, ustaw PUID=0 i PGID=0.

Dodatkowe grupy z group_add: zostają, gdy HolyArrs zmienia użytkownika.

UMASK wpływa tylko na nowe pliki. Pomiń go, żeby zostało 022: ty zapisujesz, a inni czytają. Użyj 002, gdy zapisywać ma też grupa.

Foldery multimediów

Zamontuj tylko foldery, których używasz: /movies, /tv i /music jako foldery biblioteki, a /downloads jako folder pobierania.

Wskazówka o hardlinkach (twardych dowiązaniach): każdy folder, który montujesz osobno, jest w kontenerze osobnym punktem montowania, a pliku nie da się dowiązać twardo między punktami montowania, więc importy stają się pełnymi kopiami. Jeśli chcesz hardlinków, zamiast czterech opcjonalnych punktów montowania możesz zamontować jeden wspólny folder nadrzędny (z folderami pobierania i biblioteki w środku), a Downloaderowi dać ten sam punkt montowania pod tą samą ścieżką. Folder nadrzędny musi też leżeć na jednym systemie plików. Osobne udziały sieciowe NAS lub datasety pod nim nadal kopiują. Settings > Library folders (ustawienia > foldery biblioteki) ostrzega, gdy HolyArrs musi kopiować.

HOLYARRS_SAVE_PATH jest wysyłany do Downloadera z każdym pobieraniem, więc zmienia też miejsce, w którym Downloader zapisuje. Pomiń go, żeby zostało własne ustawienie Downloadera. Jeśli go pominiesz, dodaj folder pobierania w Settings > Library folders > Extra import folders (dodatkowe foldery importu), żeby móc ręcznie importować z niego.

Zachowaj klucz główny

HolyArrs szyfruje zapisane hasła, klucze i tokeny kluczem głównym. Pierwsze uruchomienie tworzy /config/holyarrs.key.

Backupy nigdy nie zawierają tego klucza. Zachowaj jego kopię gdzie indziej. Najłatwiej: jako właściciel otwórz Settings > Backups (ustawienia > backupy) i wybierz Download key kit (pobierz zestaw z kluczem). Żeby go przywrócić, nazwij plik holyarrs.key i umieść go w folderze konfiguracji, gdy HolyArrs jest zatrzymany. Przywracanie z innym kluczem jest odrzucane. Przy nazwanym volume nie ma folderu do otwarcia: skopiuj klucz poleceniem docker cp holyarrs.key hx:/config/, tak jak w Docker Desktop. Przenosisz się na nowy komputer? Najpierw przywróć klucz, potem backup. Zobacz Backupy.

Klucz możesz też trzymać w osobnym pliku tylko do odczytu:

environment:
  - HOLYARRS_MASTER_KEY_FILE=/keys/holyarrs.key
volumes:
  - /srv/holyarrs/keys:/keys:ro

Plik musi istnieć i zawierać 32 surowe bajty, 64 cyfry szesnastkowe albo base64 dla 32 bajtów. Użytkownik PUID musi mieć możliwość jego odczytu.

Restart i przywracanie

Zostaw politykę restartu. Przywracanie jest sprawdzane i przygotowywane, a potem HolyArrs kończy działanie ze statusem 75, żeby Docker uruchomił go ponownie i zastosował przywrócenie. Zajmie się tym unless-stopped.

Żeby zaktualizować lokalny build, zbuduj go i utwórz kontener ponownie, nie ruszając punktów montowania:

docker build --file deploy/Dockerfile --tag holyarrs:local .
docker compose up -d --force-recreate

Nigdy nie usuwaj /config podczas aktualizacji. Zobacz Aktualizacje i Backupy.

Nazwy hostów i reverse proxy

Adresy IP i localhost działają od razu. Nazwa domowa, taka jak tower.local, której używasz przy pierwszej konfiguracji, zostaje zapisana za ciebie. Inne nazwy dodasz w polu Allowed host names (dozwolone nazwy hostów) w Settings > Sign-in and security (ustawienia > logowanie i bezpieczeństwo) albo w HOLYARRS_ALLOWED_HOSTS.

Gdy reverse proxy dodaje X-Forwarded-For, wpisz do HOLYARRS_TRUSTED_PROXIES tylko adres lub sieć proxy. Bez tego nie działają single sign-on, prawdziwe adresy klientów ani ciasteczko Secure, a wszyscy za proxy dzielą jeden limit logowań. Log podaje adres proxy, który trzeba dodać. Jeśli przed nim stoi kolejne proxy, na przykład Cloudflare, dodaj także jego zakresy.

W nginx wyślij oba nagłówki:

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Jeśli te dwa nagłówki mówią co innego, HolyArrs uznaje odwiedzającego za spoza twojej sieci.

Podstawy bezpieczeństwa

• Nie przekierowuj portu 6262 na routerze. Użyj VPN, na przykład Tailscale, albo reverse proxy z HTTPS.
• Utwórz konto właściciela zaraz po pierwszym uruchomieniu.
• Trzymaj kopię klucza głównego z dala od folderu konfiguracji.
• Pilnuj, żeby image był aktualny.

Szczególne konfiguracje

Docker Desktop (Windows i Mac)

Docker Desktop udostępnia foldery hosta przez warstwę, w której blokady plików bazy danych nie są bezpieczne. HolyArrs odmawia pracy z /config w takim miejscu i pokazuje rozwiązanie na porcie 6262. Użyj nazwanego volume dla /config. Foldery z multimediami mogą zostać folderami hosta.

name: HolyArrs
services:
  holyarrs:
    image: holyarrs/holyarrs:latest
    container_name: holyarrs
    environment:
      - TZ=Etc/UTC
    volumes:
      - holyarrs-config:/config
      - C:/Media/movies:/movies
    ports:
      - 6262:6262
    restart: unless-stopped

volumes:
  holyarrs-config:

Żeby przenieść stary folder konfiguracji do volume, zatrzymaj HolyArrs i wykonaj:

docker create --name hx -v holyarrs-config:/config holyarrs/holyarrs:latest
docker cp C:\old\config\. hx:/config/
docker rm hx

Żeby skopiować backupy na zewnątrz: docker cp holyarrs:/config/backups .

Na Macu, jeśli sprawdzisz, że blokady plików w twoim folderze działają, ustaw HOLYARRS_ALLOW_DESKTOP_FOLDER=1, żeby mimo to uruchomić. HolyArrs ostrzega przy każdym starcie. To nigdy nie znosi odmowy dla udziałów sieciowych.

Główny system plików tylko do odczytu

Zapisywalne muszą być tylko /config i /tmp:

services:
  holyarrs:
    read_only: true
    tmpfs:
      - /tmp

PUID, PGID i UMASK nadal działają.

Uruchomienie jako stały użytkownik

services:
  holyarrs:
    user: "1000:1000"

HolyArrs nie zmienia wtedy żadnych właścicieli, więc folder konfiguracji musi być już zapisywalny dla tego użytkownika. PUID i PGID są ignorowane, a log o tym informuje. Dotyczy to też runAsUser w Kubernetes.

Docker w trybie rootless i Podman

W trybie rootless root wewnątrz kontenera to twój własny użytkownik, a inne id są mapowane na wysokie numery na hoście. Przy PUID=1000 folder konfiguracji kończy z właścicielem, który na hoście jest obcym użytkownikiem.

Co uruchamiasz	docker info lub podman info pokazuje	Użyj
Zwykły Docker	brak rootless	PUID i PGID jak zwykle
Docker rootless	rootless w Security Options	Opcja 1
Podman rootless	rootless: true	Opcja 1 lub 2

Opcja 1. Ustaw PUID=0 i PGID=0. Jest to bezpieczne tylko w trybie rootless. Nigdy nie rób tego w zwykłym Dockerze ani na NAS-ie.

Opcja 2. Podman z keep-id, jako Quadlet w ~/.config/containers/systemd/holyarrs.container:

[Container]
Image=holyarrs/holyarrs:latest
UserNS=keep-id
User=%U:%G
Volume=%h/holyarrs/config:/config:Z
PublishPort=6262:6262
HealthCmd=["/holyarrs","-healthcheck"]
HealthInterval=30s

[Service]
Restart=always

[Install]
WantedBy=default.target

Albo jednym poleceniem:

podman run -d --name holyarrs --userns=keep-id --user "$(id -u):$(id -g)" -v ~/holyarrs/config:/config:Z -p 6262:6262 --health-cmd '["/holyarrs","-healthcheck"]' --health-interval 30s --restart always holyarrs/holyarrs:latest

• :Z jest dla systemów z SELinux. Użyj :z w folderach, które współdzielisz z Downloaderem. Nie używaj żadnego z nich na udziale sieciowym (NFS lub SMB): nie da się go ponownie oznaczyć etykietą SELinux i kontener się nie uruchomi.
• Podaj health check jako listę. Image nie ma shella.
• Zostaw politykę restartu always. Usługa Podmana, która uruchamia kontenery po restarcie komputera, startuje tylko kontenery z always.
• Żeby kontener startował po restarcie bez logowania, wykonaj raz loginctl enable-linger $USER. Potem użyj pliku Quadlet, a przy podman run wykonaj systemctl --user enable podman-restart.service.

Jeśli folder należy już do wysokiego id, najpierw zatrzymaj kontener, potem:

• Podman rootless: podman unshare chown -R 0:0 ~/holyarrs/config (Opcja 1) albo podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Docker rootless: rootlesskit chown -R 0:0 ~/holyarrs/config, wykonane przez nsenter do demona rootless (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Zbuduj własny image

Z pobranych źródeł HolyArrs:

docker build --file deploy/Dockerfile --tag holyarrs:local .

Potem użyj holyarrs:local jako image.

Rozwiązywanie problemów

Najpierw uruchom doctor. Sprawdza konfigurację, foldery, sieć i zegar, i mówi, jak naprawić każdy problem.

• Kontener działa: docker exec holyarrs /holyarrs doctor
• Kontener ciągle się restartuje: docker compose run --rm holyarrs doctor

Log i pakiet diagnostyczny opisuje strona Rozwiązywanie problemów.

Widzisz	Zrób to
Folder konfiguracji jest na folderze współdzielonym lub sieciowym	Użyj dysku lokalnego albo nazwanego volume w Docker Desktop. Na Unraidzie użyj /mnt/<pool>/appdata/holyarrs.
Folder konfiguracji jest w pamięci	Umieść /config na dysku. Na Unraidzie sprawdź, czy ścieżka puli istnieje. Na komputerze testowym pozwala na to HOLYARRS_CONFIG_IN_MEMORY=yes.
Do folderu konfiguracji nie można zapisywać	Usuń :ro i sprawdź, czy PUID:PGID są właścicielami folderu.
Dysk jest pełny	Zwolnij miejsce na dysku, na którym leży /config, potem zrestartuj.
/config nie jest zmapowany	Zobacz niżej.
Nie można zmienić użytkownika	Przywróć cztery uprawnienia (capabilities) albo użyj user: "<uid>:<gid>".
PUID/PGID nie istnieje w tym kontenerze	Id są poza zmapowanym zakresem. Zobacz Docker w trybie rootless i Podman.
Nie można odczytać zmiennej FILE__	Sprawdź ścieżkę i czy plik jest zamontowany.
Brak uprawnień (permission denied)	Sprawdź PUID, PGID i dostęp do zapisu we wszystkich folderach.
Nieznana nazwa hosta	Otwórz HolyArrs przez IP i dodaj nazwę w Allowed host names.
Importy są kopiowane	Zamontuj jeden wspólny folder. Zobacz Foldery multimediów.
Klucz główny nie pasuje	Przywróć klucz, który pasuje do tych baz danych.
Przywracanie przygotowane, ale aplikacja nie wstaje	Dodaj politykę restartu i uruchom kontener.

Co jeśli /config nie jest zmapowany?

HolyArrs nadal się uruchamia, ale ostrzega w wielu miejscach. Po usunięciu kontenera wszystko przepada. Najpierw to zapisz:

docker stop holyarrs
docker cp holyarrs:/config ./holyarrs-config

Potem zmapuj ./holyarrs-config:/config (albo nazwany volume) i utwórz kontener ponownie. W Docker Desktop (Windows i Mac) użyj nazwanego volume, a nie folderu hosta, i skopiuj dane tak, jak pokazano w Docker Desktop. Starsza konfiguracja może nadal leżeć w nienazwanym volume. Wypisz je poleceniem docker volume ls.

Powiązane strony

• Foldery
• Pierwsze uruchomienie
• NAS, Synology i Unraid
• Aktualizacje