Inštalácia

Spusti HolyArrs v Dockeri a otvor ho v prehliadači. Zaberie to pár minút.

Skôr než začneš

• Počítač s Dockerom a Docker Compose.
• Tvoje mediálne priečinky, alebo miesto, kde ich vytvoriť. Ak chceš okamžité presuny namiesto kopírovania, najprv si prečítaj Priečinky.
• Na NAS, Unraide alebo Synology pozri NAS, Synology a Unraid. Bez Dockeru pozri Prenosné archívy.

Kroky

1. Vytvor priečinok pre konfiguráciu na lokálnom disku, napríklad /srv/holyarrs/config. Nie na sieťovom zdieľaní. Na Docker Desktope použi namiesto toho pomenovaný volume. Pozri Docker Desktop.

2. Zisti používateľa a skupinu, ktoré vlastnia tvoje mediálne priečinky:

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

   Použi uid ako PUID a gid ako PGID.

3. Ulož tento obsah ako docker-compose.yml a uprav cesty:

   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. Spusti ho:

   docker compose up -d
   docker compose ps

   Keď HolyArrs odpovie, kontajner sa zobrazí ako healthy.

5. Otvor http://your-server:6262 a hneď vytvor účet vlastníka. Predvolené heslo neexistuje. Kým účet nevytvoríš, vlastníkom sa stane ten, kto HolyArrs otvorí ako prvý.

6. Pokračuj v nastavení, ktoré sa otvorí ďalej. Pozri Prvé spustenie.

Upozornenie

Predvolené heslo neexistuje. Vlastníkom nového HolyArrs sa stane ten, kto ho otvorí ako prvý. Vytvor si účet hneď.

Ak radšej používaš 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

Tag	Čo dostaneš
latest	Najnovšia verzia
1.0.0 (ľubovoľná verzia)	Presne túto verziu, nikdy sa nezmení

Vysvetlenie nastavení

Porty a priečinky

Nastavenie	Čo robí
-p 6262:6262	Webová aplikácia.
-v /config	Databázy, nastavenia, hlavný kľúč, zálohy a logy. Iba lokálny disk.
-v /movies	Voliteľné. Priečinok knižnice s filmami.
-v /tv	Voliteľné. Priečinok knižnice so seriálmi.
-v /music	Voliteľné. Priečinok knižnice s hudbou.
-v /downloads	Voliteľné. Priečinok na sťahovanie pre sťahovač. Pozri Mediálne priečinky.
--read-only=true	Voliteľné. Pozri Koreňový súborový systém iba na čítanie.
--user=1000:1000	Voliteľné. Pozri Spustenie pod pevným používateľom.

Premenné prostredia

Premenná	Čo robí
PUID, PGID	Používateľ a skupina, pod ktorými HolyArrs beží. Ak ich vynecháš, je to 1000 a 1000.
TZ	Časové pásmo, napríklad Europe/Amsterdam.
UMASK	Voliteľné. Ktoré bity oprávnení nové súbory vynechajú, napríklad 022 alebo 002.
HOLYARRS_SAVE_PATH	Voliteľné. Priečinok na ukladanie sťahovača tak, ako ho vidí sťahovač.
HOLYARRS_ALLOWED_HOSTS	Voliteľné. Ďalšie názvy hostiteľov, ktorými sa ľudia dostanú do HolyArrs, oddelené čiarkou.
HOLYARRS_TRUSTED_PROXIES	Voliteľné. Adresa alebo sieť tvojho reverse proxy.
HOLYARRS_URL_BASE	Voliteľné. Sprístupní HolyArrs pod cestou. Pozri URL base a reverse proxy.
HOLYARRS_MASTER_KEY_FILE	Voliteľné. Načíta hlavný kľúč z vlastného súboru.

Každá premenná môže prísť zo súboru. Pred názov daj FILE__ a ako hodnotu zadaj cestu k súboru:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Jeden znak nového riadka na konci súboru sa zahodí. Funguje to aj pre PUID, PGID, UMASK a TZ. Ak súbor chýba, HolyArrs sa zastaví a v logu uvedie názov premennej. Hodnotu nikdy nevypíše.

Image

Image obsahuje HolyArrs a takmer nič iné. Nemá shell, takže sa doň cez docker exec nedostaneš a nič v ňom neprezrieš. Namiesto toho si prečítaj log cez docker logs holyarrs alebo otvor logs/holyarrs.log v konfiguračnom priečinku.

Vlastné príkazy HolyArrs cez docker exec fungujú ďalej:

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

Image sú zostavené pre amd64, 64-bitové ARM a 32-bitové ARM. Na počítači s asi 2.5 GiB pamäte alebo menej zapne HolyArrs režim s nízkou pamäťou sám. Hovorí o tom prvý riadok logu.

Používateľ a skupina

Kontajner sa spustí ako root iba preto, aby sa nastavil. Ak treba, odovzdá konfiguračný priečinok používateľovi PUID:PGID a potom sa už natrvalo prepne na tohto používateľa. Prvý riadok logu ukazuje používateľa, skupinu a umask.

HolyArrs nikdy nemení vlastníka tvojich mediálnych ani sťahovacích priečinkov. Používateľovi PUID daj prístup na zápis do nich sám. Prístup na čítanie nestačí, lebo HolyArrs vytvára priečinky a presúva súbory.

Niektoré úložisko nevie meniť vlastníkov, napríklad NFS s root squash, SMB alebo pripojenie iba na čítanie. HolyArrs vtedy zapíše varovanie a pokračuje. Konfiguračný priečinok sprístupni na zápis pre PUID:PGID ručne.

Prepnutie používateľa potrebuje oprávnenia CHOWN, DAC_OVERRIDE, SETUID a SETGID. Docker ich dáva predvolene. Ak ich odoberieš, HolyArrs sa zastaví so správou. Nevráti sa na root. Ak naozaj chceš bežať ako root, nastav PUID=0 a PGID=0.

Ďalšie skupiny z group_add: sa pri prepnutí používateľa zachovajú.

UMASK ovplyvňuje iba nové súbory. Ak ho vynecháš, ostane 022: ty píšeš a ostatní čítajú. Použi 002, keď musí zapisovať aj skupina.

Mediálne priečinky

Pripoj iba priečinky, ktoré používaš: /movies, /tv a /music ako priečinky knižnice a /downloads ako priečinok na sťahovanie.

Tip k hardlinkom (pevným odkazom): každý priečinok, ktorý pripojíš samostatne, je v kontajneri samostatné pripojenie a súbor sa cez pripojenia nedá hardlinkovať, takže importy sa stanú plnými kópiami. Ak chceš hardlinky, môžeš namiesto štyroch voliteľných pripojení pripojiť jeden spoločný nadradený priečinok (s priečinkami na sťahovanie a priečinkami knižnice vo vnútri) a sťahovaču dať rovnaké pripojenie na rovnakej ceste. Nadradený priečinok musí byť tiež jeden súborový systém. Samostatné zdieľania NAS alebo datasety pod ním sa stále kopírujú. Settings > Library folders (nastavenia > priečinky knižnice) ťa upozorní, keď musí HolyArrs kopírovať.

HOLYARRS_SAVE_PATH sa posiela sťahovaču pri každom sťahovaní, takže mení aj to, kam sťahovač ukladá. Ak ho vynecháš, ostane vlastné nastavenie sťahovača. Ak ho vynecháš, pridaj priečinok na sťahovanie v Settings > Library folders > Extra import folders (ďalšie priečinky na import), aby si z neho mohol importovať ručne.

Uchovaj hlavný kľúč

HolyArrs šifruje uložené heslá, kľúče a tokeny hlavným kľúčom. Pri prvom spustení vytvorí /config/holyarrs.key.

Zálohy tento kľúč nikdy neobsahujú. Uchovaj si kópiu na inom mieste. Jednoduchý postup: ako vlastník otvor Settings > Backups a vyber Download key kit (stiahnuť balík kľúča). Ak ho chceš vrátiť, pomenuj súbor holyarrs.key a daj ho do konfiguračného priečinka, kým je HolyArrs zastavený. Obnova s iným kľúčom sa odmietne. S pomenovaným volume nie je žiadny priečinok na otvorenie: skopíruj ho dovnútra cez docker cp holyarrs.key hx:/config/ ako v Docker Desktop. Presúvaš sa na nový počítač? Najprv vráť kľúč, potom obnov zálohu. Pozri Zálohy.

Kľúč môžeš uchovávať aj vo vlastnom súbore iba na čítanie:

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

Súbor musí existovať a obsahovať 32 surových bajtov, 64 hexadecimálnych číslic alebo base64 pre 32 bajtov. Používateľ PUID ho musí vedieť čítať.

Reštart a obnova

Ponechaj politiku reštartu. Obnova sa skontroluje a pripraví, potom HolyArrs skončí so stavom 75, aby ho Docker spustil znova a obnovu použil. unless-stopped to zvládne.

Ak chceš aktualizovať lokálny build, zostav ho znova a vytvor kontajner znova bez zásahu do pripojení:

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

Počas aktualizácie nikdy neodstraňuj /config. Pozri Aktualizácie a Zálohy.

Názvy hostiteľov a reverse proxy

IP adresy a localhost fungujú hneď. Domáci názov, napríklad tower.local, ktorý použiješ pri prvom nastavení, sa uloží za teba. Ďalšie názvy pridaj v Allowed host names (povolené názvy hostiteľov) v Settings > Sign-in and security, alebo v HOLYARRS_ALLOWED_HOSTS.

Keď reverse proxy pridáva X-Forwarded-For, do HOLYARRS_TRUSTED_PROXIES daj iba adresu alebo sieť proxy. Bez toho nefunguje single sign-on, skutočné adresy klientov ani cookie Secure a všetci za proxy zdieľajú jeden limit prihlásení. Log uvádza adresu proxy, ktorú treba pridať. Ak pred ňou stojí ďalšia proxy, napríklad Cloudflare, pridaj aj jej rozsahy.

S nginx pošli obe hlavičky:

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

Ak si odporujú, HolyArrs berie návštevníka ako niekoho mimo tvojej siete.

Základy bezpečnosti

• Nepresmerúvaj port 6262 na routeri. Použi VPN, napríklad Tailscale, alebo reverse proxy s HTTPS.
• Účet vlastníka vytvor hneď po prvom spustení.
• Kópiu hlavného kľúča uchovaj mimo konfiguračného priečinka.
• Udržiavaj image aktuálny.

Špeciálne nastavenia

Docker Desktop (Windows a Mac)

Docker Desktop zdieľa priečinky hostiteľa cez vrstvu, v ktorej zámky súborov databázy nie sú bezpečné. HolyArrs tam /config odmietne a riešenie ukáže na porte 6262. Pre /config použi pomenovaný volume. Mediálne priečinky môžu zostať priečinkami hostiteľa.

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:

Ak chceš presunúť starý konfiguračný priečinok do volume, zastav HolyArrs a spusti:

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

Zálohy skopíruješ von takto: docker cp holyarrs:/config/backups .

Na Macu, ak si overil, že zámky súborov v tvojom priečinku fungujú, nastav HOLYARRS_ALLOW_DESKTOP_FOLDER=1, aby sa HolyArrs spustil aj tak. HolyArrs varuje pri každom spustení. Odmietnutie pre sieťové zdieľania to nikdy nezruší.

Koreňový súborový systém iba na čítanie

Zapisovateľné musí byť iba /config a /tmp:

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

PUID, PGID a UMASK fungujú ďalej.

Spustenie pod pevným používateľom

services:
  holyarrs:
    user: "1000:1000"

HolyArrs potom nemení žiadnych vlastníkov, takže konfiguračný priečinok musí byť už zapisovateľný pre tohto používateľa. PUID a PGID sa ignorujú a log to uvedie. Týka sa to aj runAsUser v Kubernetes.

Rootless Docker a Podman

V rootless režime je root vo vnútri kontajnera tvoj vlastný používateľ a ostatné id sa na hostiteľovi mapujú na vysoké čísla. S PUID=1000 skončí konfiguračný priečinok vo vlastníctve cudzieho používateľa na hostiteľovi.

Čo používaš	docker info alebo podman info ukazuje	Použi
Normálny Docker	žiadne rootless	PUID a PGID ako obvykle
Rootless Docker	rootless pod Security Options	Možnosť 1
Rootless Podman	rootless: true	Možnosť 1 alebo 2

Možnosť 1. Nastav PUID=0 a PGID=0. Bezpečné je to iba v rootless režime. Nikdy to nerob s normálnym Dockerom ani na NAS.

Možnosť 2. Podman s keep-id, ako Quadlet v ~/.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

Alebo ako jeden príkaz:

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 je pre systémy so SELinuxom. Na priečinkoch, ktoré zdieľa sťahovač, použi :z. Na sieťovom zdieľaní (NFS alebo SMB) nepoužívaj ani jedno: štítok sa naň nedá znova nastaviť a kontajner by sa nespustil.
• Health check zadaj ako zoznam. Image nemá shell.
• Politiku reštartu ponechaj always. Služba Podmanu na spustenie po reštarte spúšťa iba kontajnery s always.
• Ak chceš spustenie po reštarte bez prihlásenia, spusti jednorazovo loginctl enable-linger $USER. Potom použi súbor Quadlet, alebo pre podman run spusti systemctl --user enable podman-restart.service.

Ak priečinok už patrí vysokému id, najprv zastav kontajner a potom:

• Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (Možnosť 1) alebo podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, spustený cez nsenter do rootless daemona (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Zostav si vlastný image

Z kópie repozitára HolyArrs:

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

Potom ako image použi holyarrs:local.

Riešenie problémov

Najprv spusti doctor. Skontroluje konfiguráciu, priečinky, sieť a hodiny a povie ti, ako opraviť každý problém.

• Kontajner beží: docker exec holyarrs /holyarrs doctor
• Kontajner sa stále reštartuje: docker compose run --rm holyarrs doctor

Log a balík pre podporu nájdeš v Riešenie problémov.

Vidíš	Urob toto
Config folder is on a shared or network folder (konfiguračný priečinok je na zdieľanom alebo sieťovom priečinku)	Použi lokálny disk, alebo pomenovaný volume na Docker Desktope. Na Unraide použi /mnt/<pool>/appdata/holyarrs.
Config folder is in memory (konfiguračný priečinok je v pamäti)	Daj /config na disk. Na Unraide skontroluj, či cesta k poolu existuje. Pre testovací počítač to povolí HOLYARRS_CONFIG_IN_MEMORY=yes.
Config folder cannot be written (do konfiguračného priečinka sa nedá zapisovať)	Odstráň :ro a skontroluj, či priečinok vlastní PUID:PGID.
Disk is full (disk je plný)	Uvoľni miesto na disku, na ktorom je /config, a reštartuj.
/config is not mapped (nie je namapovaný)	Pozri nižšie.
Cannot switch user (nedá sa prepnúť používateľ)	Pridaj späť štyri oprávnenia, alebo použi user: "<uid>:<gid>".
PUID/PGID does not exist inside this container (PUID/PGID v tomto kontajneri neexistuje)	Id sú mimo namapovaného rozsahu. Pozri Rootless Docker a Podman.
A FILE__ variable cannot be read (premennú so súborom sa nedá prečítať)	Skontroluj cestu a či je súbor pripojený.
Permission denied (prístup zamietnutý)	Skontroluj PUID, PGID a prístup na zápis vo všetkých priečinkoch.
Unknown host name (neznámy názov hostiteľa)	Otvor HolyArrs cez IP a pridaj názov do Allowed host names.
Imports are copied (importy sa kopírujú)	Pripoj jeden spoločný priečinok. Pozri Mediálne priečinky.
Master key does not match (hlavný kľúč nesedí)	Vráť kľúč, ktorý patrí k týmto databázam.
Restore staged but the app stays down (obnova je pripravená, ale aplikácia ostáva vypnutá)	Pridaj politiku reštartu a spusti kontajner.

Zabudol si namapovať /config?

HolyArrs sa aj tak spustí, ale varuje všade. Všetko sa stratí, keď sa kontajner odstráni. Najprv to ulož:

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

Potom namapuj ./holyarrs-config:/config (alebo pomenovaný volume) a vytvor kontajner znova. Na Docker Desktope (Windows a Mac) použi pomenovaný volume, nie priečinok hostiteľa, a dáta skopíruj dovnútra tak, ako je ukázané v Docker Desktop. Staršie nastavenie môže byť ešte v nepomenovanom volume. Zobrazíš ich cez docker volume ls.

Súvisiace stránky

• Priečinky
• Prvé spustenie
• NAS, Synology a Unraid
• Aktualizácie