Instalace

Jsem tu nový

Spusť HolyArrs v Dockeru a otevři ho v prohlížeči. Zabere to pár minut.

Než začneš

Počítač s Dockerem a Docker Compose.
Tvoje složky s médii, nebo místo, kde je vytvoříš. Pokud chceš okamžité přesuny místo kopírování, přečti si nejdřív Složky.
Na NAS, Unraidu nebo Synology viz NAS, Synology a Unraid. Bez Dockeru viz Přenosné archivy.

Kroky

Vytvoř složku pro konfiguraci na místním disku, například /srv/holyarrs/config. Ne na sdílené složce. V Docker Desktopu použij místo ní pojmenovaný volume. Viz Docker Desktop.
Zjisti uživatele a skupinu, kterým patří tvoje složky s médii:
Terminal window
```
id youruser
# uid=1000(youruser) gid=1000(youruser)
```
Použij uid jako PUID a gid jako PGID.

Ulož tohle jako 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

Spusť ho:
Terminal window
```
docker compose up -d
docker compose ps
```
Jakmile HolyArrs odpoví, kontejner se zobrazí jako healthy.
Otevři http://your-server:6262 a hned vytvoř účet vlastníka. Žádné výchozí heslo neexistuje. Dokud účet nevytvoříš, vlastníkem se stane ten, kdo HolyArrs otevře jako první.
Pokračuj nastavením, které se otevře dál. Viz První spuštění.

Pokud dáváš přednost 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	Co dostaneš
`latest`	Nejnovější verzi
`1.0.0` (jakákoli verze)	Přesně tu verzi, nikdy se nemění

Vysvětlení nastavení

Porty a složky

Nastavení	K čemu je
`-p 6262:6262`	Webová aplikace.
`-v /config`	Databáze, nastavení, hlavní klíč, zálohy a logy. Jen místní disk.
`-v /movies`	Volitelné. Složka knihovny s filmy.
`-v /tv`	Volitelné. Složka knihovny se seriály.
`-v /music`	Volitelné. Složka knihovny s hudbou.
`-v /downloads`	Volitelné. Složka pro stahování stahovače. Viz Složky s médii.
`--read-only=true`	Volitelné. Viz Kořenový souborový systém jen pro čtení.
`--user=1000:1000`	Volitelné. Viz Spuštění pod pevně daným uživatelem.

Proměnné prostředí

Proměnná	K čemu je
`PUID`, `PGID`	Uživatel a skupina, pod kterými HolyArrs běží. Když je vynecháš, je to 1000 a 1000.
`TZ`	Časové pásmo, například `Europe/Amsterdam`.
`UMASK`	Volitelné. Která oprávnění nové soubory nedostanou, například `022` nebo `002`.
`HOLYARRS_SAVE_PATH`	Volitelné. Složka pro ukládání stahovače, tak jak ji vidí stahovač.
`HOLYARRS_ALLOWED_HOSTS`	Volitelné. Další názvy hostitele, přes které lidé HolyArrs otevírají, oddělené čárkou.
`HOLYARRS_TRUSTED_PROXIES`	Volitelné. Adresa nebo síť tvé reverzní proxy.
`HOLYARRS_URL_BASE`	Volitelné. Provozuje HolyArrs pod cestou. Viz URL base a reverzní proxy.
`HOLYARRS_MASTER_KEY_FILE`	Volitelné. Načte hlavní klíč z vlastního souboru.

Každá proměnná může pocházet ze souboru. Před název dej FILE__ a jako hodnotu zadej cestu k souboru:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Jeden znak nového řádku na konci souboru se zahodí. Funguje to i pro PUID, PGID, UMASK a TZ. Když soubor chybí, HolyArrs se zastaví a v logu uvede název proměnné. Hodnotu nikdy nevypíše.

Image

Image obsahuje HolyArrs a skoro nic dalšího. Nemá shell, takže se do něj přes docker exec nedostaneš a nemůžeš se v něm rozhlížet. Místo toho si přečti log příkazem docker logs holyarrs, nebo otevři logs/holyarrs.log v konfigurační složce.

Vlastní příkazy HolyArrs přes docker exec fungují dál:

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

Imagy jsou sestavené pro amd64, 64bitové ARM a 32bitové ARM. Na počítači s asi 2.5 GiB paměti nebo méně HolyArrs sám zapne režim s nízkou pamětí. Říká to první řádek logu.

Uživatel a skupina

Kontejner startuje jako root jen proto, aby se připravil. Když je potřeba, předá konfigurační složku uživateli PUID:PGID a pak se natrvalo přepne na něj. První řádek logu ukazuje uživatele, skupinu a umask.

HolyArrs nikdy nemění vlastníka tvých složek s médii ani se stahováním. Přístup pro zápis dej uživateli PUID sám. Přístup pro čtení nestačí, protože HolyArrs vytváří složky a přesouvá soubory.

Některé úložiště vlastníky měnit neumí, třeba NFS s root squash, SMB nebo připojení jen pro čtení. HolyArrs pak zapíše varování a pokračuje dál. Udělej konfigurační složku zapisovatelnou pro PUID:PGID ručně.

Přepnutí uživatele potřebuje oprávnění CHOWN, DAC_OVERRIDE, SETUID a SETGID. Docker je dává ve výchozím stavu. Pokud je odebereš, HolyArrs se zastaví a vypíše zprávu. Na root se nevrátí. Když chceš skutečně běžet jako root, nastav PUID=0 a PGID=0.

Další skupiny z group_add: se při přepnutí uživatele zachovají.

UMASK ovlivní jen nové soubory. Když ho vynecháš, zůstane 022, kdy ty zapisuješ a ostatní čtou. Použij 002, když má zapisovat i skupina.

Složky s médii

Připoj jen složky, které používáš: /movies, /tv a /music jako složky knihovny a /downloads jako složku pro stahování.

Tip k hardlinkům (pevný odkaz): každá složka, kterou připojíš zvlášť, je uvnitř kontejneru samostatné připojení a soubor se přes připojení hardlinkem propojit nedá, takže importy se stanou plnými kopiemi. Když chceš hardlinky, připoj místo čtyř volitelných připojení jednu sdílenou nadřazenou složku (se složkami pro stahování a knihovny uvnitř) a stahovači dej stejné připojení na stejné cestě. Nadřazená složka musí být také jeden souborový systém. Samostatné sdílené složky NAS nebo datasety pod ní se pořád kopírují. Settings > Library folders (nastavení > složky knihovny) tě varuje, když HolyArrs musí kopírovat.

HOLYARRS_SAVE_PATH se stahovači posílá s každým stahováním, takže mění i to, kam stahovač ukládá. Vynech ho, pokud chceš zachovat nastavení samotného stahovače. Když ho vynecháš, přidej složku pro stahování v Settings > Library folders > Extra import folders (další složky pro import), abys z ní mohl importovat ručně.

Uchovej hlavní klíč

HolyArrs šifruje uložená hesla, klíče a tokeny hlavním klíčem. První spuštění vytvoří /config/holyarrs.key.

Zálohy tento klíč nikdy neobsahují. Uchovej si kopii jinde. Snadná cesta: jako vlastník otevři Settings > Backups (nastavení > zálohy) a vyber Download key kit (stáhnout sadu s klíčem). Když ho chceš vrátit zpět, pojmenuj soubor holyarrs.key a vlož ho do konfigurační složky, zatímco je HolyArrs zastavený. Obnova s jiným klíčem se odmítne. U pojmenovaného volume není žádná složka k otevření: zkopíruj ho dovnitř příkazem docker cp holyarrs.key hx:/config/ jako v Docker Desktop. Stěhuješ se na nový počítač? Nejdřív vrať klíč zpět, potom obnov zálohu. Viz Zálohy.

Klíč můžeš mít i ve vlastním souboru jen pro čtení:

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

Soubor musí existovat a obsahovat 32 surových bajtů, 64 hexadecimálních číslic nebo base64 pro 32 bajtů. Uživatel PUID ho musí umět přečíst.

Restart a obnova

Ponech zásadu restartu. Obnova se zkontroluje a připraví, potom HolyArrs skončí se stavem 75, aby ho Docker spustil znovu a obnovu použil. S unless-stopped to funguje.

Když chceš aktualizovat místní build, sestav ho znovu a vytvoř kontejner znovu, aniž bys sahal na připojení:

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

Při aktualizaci nikdy neodstraňuj /config. Viz Aktualizace a Zálohy.

Názvy hostitele a reverzní proxy

IP adresy a localhost fungují hned. Domácí název jako tower.local, který použiješ při prvním nastavení, se uloží za tebe. Další názvy přidej v Allowed host names (povolené názvy hostitele) v Settings > Sign-in and security (nastavení > přihlášení a zabezpečení), nebo v HOLYARRS_ALLOWED_HOSTS.

Když reverzní proxy přidává X-Forwarded-For, dej do HOLYARRS_TRUSTED_PROXIES jen adresu nebo síť proxy. Bez toho nefunguje single sign-on, skutečné adresy klientů ani cookie Secure a všichni za proxy sdílejí jeden limit přihlášení. Log uvede adresu proxy, kterou přidat. Pokud před ní stojí další proxy, třeba Cloudflare, přidej i její rozsahy.

S nginx pošli obě hlavičky:

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

Pokud se obě liší, HolyArrs bere návštěvníka jako někoho mimo tvou síť.

Základy zabezpečení

Nepřesměrovávej port 6262 na routeru. Použij VPN, třeba Tailscale, nebo reverzní proxy s HTTPS.
Účet vlastníka vytvoř hned po prvním spuštění.
Uchovej kopii hlavního klíče mimo konfigurační složku.
Udržuj image aktuální.

Zvláštní nastavení

Docker Desktop (Windows a Mac)

Docker Desktop sdílí složky hostitele vrstvou, kde zámky souborů databáze nejsou bezpečné. HolyArrs tam /config odmítne a opravu ukáže na portu 6262. Pro /config použij pojmenovaný volume. Složky s médii můžou zůstat složkami hostitele.

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:

Starou konfigurační složku přesuneš do volume tak, že zastavíš HolyArrs a spustíš:

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

Zálohy zkopíruješ ven takto: docker cp holyarrs:/config/backups .

Na Macu, pokud sis ověřil, že zámky souborů ve tvé složce fungují, nastav HOLYARRS_ALLOW_DESKTOP_FOLDER=1 a HolyArrs se přesto spustí. HolyArrs při každém startu varuje. Odmítnutí u sdílených složek tohle nikdy nezruší.

Kořenový souborový systém jen pro čtení

Zapisovatelné musí být jen /config a /tmp:

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

PUID, PGID a UMASK fungují dál.

Spuštění pod pevně daným uživatelem

services:
  holyarrs:
    user: "1000:1000"

HolyArrs pak nemění žádné vlastníky, takže konfigurační složka musí být tímto uživatelem už zapisovatelná. PUID a PGID se ignorují a log to řekne. Platí to i pro Kubernetes runAsUser.

Rootless Docker a Podman

V režimu rootless je root uvnitř kontejneru tvůj vlastní uživatel a ostatní id se na hostiteli mapují na vysoká čísla. S PUID=1000 pak konfigurační složka na hostiteli skončí u cizího vlastníka.

Co používáš	`docker info` nebo `podman info` ukáže	Použij
Normální Docker	žádné `rootless`	`PUID` a `PGID` jako obvykle
Rootless Docker	`rootless` v Security Options	Možnost 1
Rootless Podman	`rootless: true`	Možnost 1 nebo 2

Možnost 1. Nastav PUID=0 a PGID=0. Je to bezpečné jen v režimu rootless. Nikdy to nedělej s normálním Dockerem ani na NAS.

Možnost 2. Podman s keep-id, jako 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

Nebo jedním příkazem:

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 pro systémy se SELinuxem. Na složkách, které sdílí stahovač, použij :z. Na sdílené složce (NFS nebo SMB) nepoužívej ani jedno: nejde přeznačit a kontejner by nenastartoval.
Health check zadej jako seznam. Image nemá shell.
Zásadu restartu nech always. Služba Podmanu pro start po restartu spouští jen kontejnery s always.
Když chceš, aby se po restartu spustil bez přihlášení, spusť jednou loginctl enable-linger $USER. Pak použij soubor Quadlet, nebo u podman run spusť systemctl --user enable podman-restart.service.

Pokud složka už patří vysokému id, nejdřív zastav kontejner a potom:

Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (možnost 1) nebo podman unshare chown -R 1000:1000 ~/holyarrs/config.
Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, spuštěné přes nsenter do rootless daemona (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Sestav si vlastní image

Z kopie repozitáře HolyArrs:

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

Potom jako image použij holyarrs:local.

Řešení potíží

Nejdřív spusť doctor. Zkontroluje konfiguraci, složky, síť i hodiny a řekne ti, jak každý problém opravit.

Kontejner běží: docker exec holyarrs /holyarrs doctor
Kontejner se pořád restartuje: docker compose run --rm holyarrs doctor

Log a balíček pro podporu najdeš v Řešení potíží.

Vidíš	Udělej
Config folder is on a shared or network folder	Použij místní disk, nebo pojmenovaný volume v Docker Desktopu. Na Unraidu použij `/mnt/<pool>/appdata/holyarrs`.
Config folder is in memory	Dej `/config` na disk. Na Unraidu zkontroluj, že cesta k poolu existuje. Na testovacím stroji to povolí `HOLYARRS_CONFIG_IN_MEMORY=yes`.
Config folder cannot be written	Odstraň `:ro` a zkontroluj, že složka patří `PUID:PGID`.
Disk is full	Uvolni místo na disku, který drží `/config`, a restartuj.
`/config` is not mapped	Viz níže.
Cannot switch user	Vrať zpět čtyři oprávnění, nebo použij `user: "<uid>:<gid>"`.
PUID/PGID does not exist inside this container	Id jsou mimo namapovaný rozsah. Viz Rootless Docker a Podman.
A `FILE__` variable cannot be read	Zkontroluj cestu a že je soubor připojený.
Permission denied	Zkontroluj `PUID`, `PGID` a přístup pro zápis ve všech složkách.
Unknown host name	Otevři HolyArrs přes IP a přidej název do Allowed host names.
Imports are copied	Připoj jednu sdílenou složku. Viz Složky s médii.
Master key does not match	Vrať klíč, který patří k těm databázím.
Restore staged but the app stays down	Přidej zásadu restartu a spusť kontejner.

Zapomněl jsi namapovat /config?

HolyArrs se přesto spustí, ale všude varuje. Po odstranění kontejneru se všechno ztratí. Nejdřív to ulož:

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

Potom namapuj ./holyarrs-config:/config (nebo pojmenovaný volume) a vytvoř kontejner znovu. V Docker Desktopu (Windows a Mac) použij pojmenovaný volume, ne složku hostitele, a data do něj zkopíruj, jak je ukázáno v Docker Desktop. Starší nastavení může být pořád v nepojmenovaném volume. Vypíšeš je příkazem docker volume ls.

Související

HolyArrs je zdarma. Pokud ti ušetřil čas, dej mu hvězdičku na GitHubu, podpoř ho sponzorstvím nebo kup mi kávu.