Instalacija

Pokreni HolyArrs u Dockeru i otvori ga u pregledniku. Treba ti nekoliko minuta.

Prije nego počneš

• Računalo s Dockerom i Docker Composeom.
• Tvoje mape s medijima ili mjesto gdje ćeš ih napraviti. Ako želiš trenutačno premještanje umjesto kopiranja, prvo pročitaj Mape.
• Na NAS-u, Unraidu ili Synologyju pogledaj NAS, Synology i Unraid. Bez Dockera pogledaj Prijenosne arhive.

Koraci

1. Napravi mapu za konfiguraciju na lokalnom disku, na primjer /srv/holyarrs/config. Ne na mrežnom dijeljenom resursu. Na Docker Desktopu umjesto toga koristi imenovani volume. Pogledaj Docker Desktop.

2. Pronađi korisnika i grupu koji su vlasnici tvojih mapa s medijima:

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

   Upotrijebi uid kao PUID, a gid kao PGID.

3. Spremi ovo kao docker-compose.yml i promijeni putanje:

   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. Pokreni ga:

   docker compose up -d
   docker compose ps

   Container se prikazuje kao healthy čim HolyArrs počne odgovarati.

5. Otvori http://your-server:6262 i odmah napravi račun vlasnika. Zadane lozinke nema. Dok ga ne napraviš, tko god prvi otvori HolyArrs postaje vlasnik.

6. Slijedi postavljanje koje se otvori sljedeće. Pogledaj Prvo pokretanje.

Oprez

Zadane lozinke nema. Tko god prvi otvori novi HolyArrs postaje vlasnik. Napravi račun odmah.

Ako više voliš 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

Image tag

Tag	Što dobiješ
latest	Najnoviju verziju
1.0.0 (bilo koja verzija)	Točno tu verziju, nikad se ne mijenja

Objašnjenje postavki

Portovi i mape

Postavka	Što radi
-p 6262:6262	Web aplikacija.
-v /config	Baze podataka, postavke, glavni ključ, backupi i logovi. Samo lokalni disk.
-v /movies	Neobavezno. Mapa biblioteke za filmove.
-v /tv	Neobavezno. Mapa biblioteke za serije.
-v /music	Neobavezno. Mapa biblioteke za glazbu.
-v /downloads	Neobavezno. Mapa za preuzimanja tvog preuzimatelja. Pogledaj Mape s medijima.
--read-only=true	Neobavezno. Pogledaj Datotečni sustav root samo za čitanje.
--user=1000:1000	Neobavezno. Pogledaj Pokretanje kao fiksni korisnik.

Varijable okoline

Varijabla	Što radi
PUID, PGID	Korisnik i grupa pod kojima HolyArrs radi. Ako ih izostaviš, bit će 1000 i 1000.
TZ	Vremenska zona, na primjer Europe/Amsterdam.
UMASK	Neobavezno. Koje bitove dozvola nove datoteke izostavljaju, na primjer 022 ili 002.
HOLYARRS_SAVE_PATH	Neobavezno. Mapa u koju preuzimatelj sprema, onako kako je preuzimatelj vidi.
HOLYARRS_ALLOWED_HOSTS	Neobavezno. Dodatna imena hostova kojima ljudi otvaraju HolyArrs, odvojena zarezima.
HOLYARRS_TRUSTED_PROXIES	Neobavezno. Adresa ili mreža tvog reverse proxyja.
HOLYARRS_URL_BASE	Neobavezno. Posluži HolyArrs ispod neke putanje. Pogledaj URL base i reverse proxyji.
HOLYARRS_MASTER_KEY_FILE	Neobavezno. Pročitaj glavni ključ iz njegove vlastite datoteke.

Svaka varijabla može doći iz datoteke. Stavi FILE__ ispred imena i za vrijednost upiši putanju do datoteke:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Jedan novi red na kraju datoteke se odbacuje. To radi i za PUID, PGID, UMASK i TZ. Ako datoteke nema, HolyArrs se zaustavi i u logu navede ime varijable. Vrijednost nikad ne ispisuje.

Image

Image sadrži HolyArrs i skoro ništa drugo. Nema shell, pa u njega ne možeš ući s docker exec da razgledaš. Umjesto toga pročitaj log s docker logs holyarrs ili otvori logs/holyarrs.log u mapi s konfiguracijom.

Vlastite naredbe HolyArrsa i dalje rade kroz docker exec:

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

Imagei se grade za amd64, 64-bitni ARM i 32-bitni ARM. Na računalu s oko 2.5 GiB memorije ili manje HolyArrs sam uključuje način rada s malo memorije. Prva linija loga to kaže.

Korisnik i grupa

Container se pokreće kao root samo da se postavi. Mapu s konfiguracijom dodijeli korisniku PUID:PGID kad je potrebno, a zatim trajno prijeđe na tog korisnika. Prva linija loga prikazuje korisnika, grupu i umask.

HolyArrs nikad ne mijenja vlasnika tvojih mapa s medijima ni mapa za preuzimanja. Daj korisniku PUID pravo pisanja u njih ručno. Pravo čitanja nije dovoljno, jer HolyArrs pravi mape i premješta datoteke.

Neka pohrana ne može mijenjati vlasnike, na primjer NFS s root squashom, SMB ili mount samo za čitanje. HolyArrs tada zapiše upozorenje u log i nastavi. Mapu s konfiguracijom ručno učini upisivom za PUID:PGID.

Za promjenu korisnika trebaju mogućnosti CHOWN, DAC_OVERRIDE, SETUID i SETGID. Docker ih prema zadanim postavkama daje. Ako ih ukloniš, HolyArrs se zaustavi uz poruku. Ne vraća se na root. Da bi stvarno radio kao root, postavi PUID=0 i PGID=0.

Dodatne grupe iz group_add: ostaju kad HolyArrs promijeni korisnika.

UMASK utječe samo na nove datoteke. Izostavi ga da zadržiš 022, gdje ti pišeš, a drugi čitaju. Upotrijebi 002 kad i grupa mora moći pisati.

Mape s medijima

Montiraj samo mape koje koristiš: /movies, /tv i /music kao mape biblioteke, a /downloads kao mapu za preuzimanja.

Savjet za hardlinkove (tvrda veza): svaka mapa koju montiraš zasebno je zaseban mount unutar containera, a datoteka se ne može povezati hardlinkom preko mountova, pa uvozi postaju potpune kopije. Ako želiš hardlinkove, umjesto četiri neobavezna mounta možeš montirati jednu zajedničku nadređenu mapu (s preuzimanjima i mapama biblioteke unutar nje) i dati preuzimatelju isti mount na istoj putanji. Nadređena mapa također mora biti jedan datotečni sustav. Zasebni NAS dijeljeni resursi ili datasetovi unutar nje i dalje kopiraju. Settings > Library folders (postavke > mape biblioteke) upozorava te kad HolyArrs mora kopirati.

HOLYARRS_SAVE_PATH se šalje preuzimatelju sa svakim preuzimanjem, pa mijenja i mjesto gdje preuzimatelj sprema. Izostavi ga da zadržiš vlastitu postavku preuzimatelja. Ako ga izostaviš, dodaj mapu za preuzimanja pod Settings > Library folders > Extra import folders (dodatne mape za uvoz) da iz nje možeš uvoziti ručno.

Čuvaj glavni ključ

HolyArrs šifrira spremljene lozinke, ključeve i tokene glavnim ključem. Prvo pokretanje pravi /config/holyarrs.key.

Backupi nikad ne sadrže ovaj ključ. Čuvaj kopiju negdje drugdje. Jednostavno: kao vlasnik otvori Settings > Backups i odaberi Download key kit (preuzmi paket s ključem). Da ga vratiš, datoteku nazovi holyarrs.key i stavi je u mapu s konfiguracijom dok je HolyArrs zaustavljen. Obnova s drugim ključem se odbija. S imenovanim volumeom nema mape koju bi otvorio: kopiraj ga unutra s docker cp holyarrs.key hx:/config/ kao u Docker Desktop. Seliš na novo računalo? Prvo vrati ključ, zatim obnovi backup. Pogledaj Backupi.

Ključ možeš čuvati i u njegovoj vlastitoj datoteci samo za čitanje:

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

Datoteka mora postojati i sadržavati 32 sirova bajta, 64 heksadecimalne znamenke ili base64 za 32 bajta. Korisnik PUID mora je moći čitati.

Ponovno pokretanje i obnova

Zadrži pravilo ponovnog pokretanja. Obnova se provjeri i pripremi, zatim HolyArrs izlazi sa statusom 75 da ga Docker ponovno pokrene i primijeni je. unless-stopped to rješava.

Za ažuriranje lokalnog builda ponovno izgradi i ponovno stvori container bez diranja mountova:

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

Nikad ne uklanjaj /config tijekom ažuriranja. Pogledaj Ažuriranja i Backupi.

Imena hostova i reverse proxyji

IP adrese i localhost rade odmah. Kućno ime poput tower.local koje koristiš pri prvom postavljanju sprema se automatski. Druga imena dodaj pod Allowed host names (dopuštena imena hostova) u Settings > Sign-in and security, ili u HOLYARRS_ALLOWED_HOSTS.

Kad reverse proxy dodaje X-Forwarded-For, u HOLYARRS_TRUSTED_PROXIES stavi samo adresu ili mrežu proxyja. Bez toga ne rade single sign-on, prave adrese klijenata i Secure kolačić, a svi iza proxyja dijele jedno ograničenje prijave. Log navodi adresu proxyja koju treba dodati. Ako ispred stoji drugi proxy, na primjer Cloudflare, dodaj i njegove raspone.

S nginxom pošalji oba headera:

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

Ako se ta dva ne slažu, HolyArrs posjetitelja tretira kao nekoga izvan tvoje mreže.

Osnove sigurnosti

• Ne prosljeđuj port 6262 na svom routeru. Koristi VPN poput Tailscalea ili reverse proxy s HTTPS-om.
• Napravi račun vlasnika odmah nakon prvog pokretanja.
• Čuvaj kopiju glavnog ključa daleko od mape s konfiguracijom.
• Održavaj image ažurnim.

Posebna postavljanja

Docker Desktop (Windows i Mac)

Docker Desktop dijeli mape računala kroz sloj u kojem zaključavanje datoteka baze podataka nije sigurno. HolyArrs odbija /config tamo i na portu 6262 prikazuje rješenje. Za /config koristi imenovani volume. Mape s medijima mogu ostati mape računala.

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:

Da staru mapu s konfiguracijom prebaciš u volume, zaustavi HolyArrs i izvrši:

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

Da kopiraš backupe van: docker cp holyarrs:/config/backups .

Na Macu, ako si provjerio da zaključavanje datoteka radi u tvojoj mapi, postavi HOLYARRS_ALLOW_DESKTOP_FOLDER=1 da svejedno pokreneš. HolyArrs upozorava pri svakom pokretanju. Ovo nikad ne ukida odbijanje za mrežne dijeljene resurse.

Datotečni sustav root samo za čitanje

Samo /config i /tmp moraju biti upisivi:

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

PUID, PGID i UMASK i dalje rade.

Pokretanje kao fiksni korisnik

services:
  holyarrs:
    user: "1000:1000"

HolyArrs tada ne mijenja vlasnike, pa mapa s konfiguracijom već mora biti upisiva za tog korisnika. PUID i PGID se ignoriraju, a log to kaže. Ovo pokriva i Kubernetes runAsUser.

Rootless Docker i Podman

U rootless načinu root unutar containera je tvoj vlastiti korisnik, a ostali id-ovi mapiraju se na visoke brojeve na računalu. S PUID=1000 mapa s konfiguracijom završi u vlasništvu stranca na računalu.

Što koristiš	docker info ili podman info prikazuje	Upotrijebi
Normalni Docker	nema rootless	PUID i PGID kao i obično
Rootless Docker	rootless pod Security Options	Opciju 1
Rootless Podman	rootless: true	Opciju 1 ili 2

Opcija 1. Postavi PUID=0 i PGID=0. Ovo je sigurno samo u rootless načinu. Nikad to ne radi s normalnim Dockerom ni na NAS-u.

Opcija 2. Podman s keep-id, kao Quadlet u ~/.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

Ili kao jedna naredba:

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 za sustave sa SELinuxom. Koristi :z na mapama koje dijeli preuzimatelj. Ne koristi nijedno na mrežnom dijeljenom resursu (NFS ili SMB): ne može se ponovno označiti i container se ne bi pokrenuo.
• Provjeru stanja zadaj kao popis. Image nema shell.
• Zadrži pravilo ponovnog pokretanja always. Podmanov servis za pokretanje nakon ponovnog pokretanja računala pokreće samo always containere.
• Da se pokrene nakon ponovnog pokretanja računala bez prijave, jednom izvrši loginctl enable-linger $USER. Zatim koristi Quadlet datoteku, ili za podman run izvrši systemctl --user enable podman-restart.service.

Ako mapa već pripada visokom id-u, prvo zaustavi container, zatim:

• Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (Opcija 1) ili podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, izvršeno kroz nsenter u rootless daemon (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Izgradi vlastiti image

Iz svog HolyArrs checkouta:

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

Zatim kao image upotrijebi holyarrs:local.

Rješavanje problema

Prvo pokreni doctor. Provjerava konfiguraciju, mape, mrežu i sat, i kaže ti kako riješiti svaki problem.

• Container radi: docker exec holyarrs /holyarrs doctor
• Container se stalno ponovno pokreće: docker compose run --rm holyarrs doctor

Za log i paket za podršku pogledaj Rješavanje problema.

Vidiš	Napravi ovo
Config folder is on a shared or network folder (mapa s konfiguracijom je na dijeljenoj ili mrežnoj mapi)	Koristi lokalni disk ili imenovani volume na Docker Desktopu. Na Unraidu koristi /mnt/<pool>/appdata/holyarrs.
Config folder is in memory (mapa s konfiguracijom je u memoriji)	Stavi /config na disk. Na Unraidu provjeri postoji li putanja poola. Za testno računalo to dopušta HOLYARRS_CONFIG_IN_MEMORY=yes.
Config folder cannot be written (u mapu s konfiguracijom se ne može pisati)	Ukloni :ro i provjeri da PUID:PGID posjeduju mapu.
Disk is full (disk je pun)	Oslobodi prostor na disku koji sadrži /config, zatim ponovno pokreni.
/config is not mapped (/config nije mapiran)	Pogledaj dolje.
Cannot switch user (ne mogu promijeniti korisnika)	Vrati četiri mogućnosti ili koristi user: "<uid>:<gid>".
PUID/PGID does not exist inside this container (PUID/PGID ne postoji unutar ovog containera)	Id-ovi su izvan mapiranog raspona. Pogledaj Rootless Docker i Podman.
A FILE__ variable cannot be read (varijabla FILE__ se ne može pročitati)	Provjeri putanju i je li datoteka montirana.
Permission denied (pristup odbijen)	Provjeri PUID, PGID i pravo pisanja na svim mapama.
Unknown host name (nepoznato ime hosta)	Otvori HolyArrs preko IP adrese i dodaj ime pod Allowed host names.
Imports are copied (uvozi se kopiraju)	Montiraj jednu zajedničku mapu. Pogledaj Mape s medijima.
Master key does not match (glavni ključ se ne podudara)	Vrati ključ koji pripada tim bazama podataka.
Restore staged but the app stays down (obnova je pripremljena, ali aplikacija ne radi)	Dodaj pravilo ponovnog pokretanja i pokreni container.

Što ako /config nije mapiran?

HolyArrs se i dalje pokreće, ali posvuda upozorava. Sve se izgubi kad se container ukloni. Prvo to spremi:

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

Zatim mapiraj ./holyarrs-config:/config (ili imenovani volume) i ponovno stvori container. Na Docker Desktopu (Windows i Mac) koristi imenovani volume, a ne mapu računala, i kopiraj podatke unutra kako je prikazano u Docker Desktop. Starije postavljanje može još biti u neimenovanom volumeu. Ispiši ih s docker volume ls.

Povezane stranice

• Mape
• Prvo pokretanje
• NAS, Synology i Unraid
• Ažuriranja