Instalare

Rulează HolyArrs în Docker și deschide-l în browser. Durează câteva minute.

Înainte să începi

• Un aparat cu Docker și Docker Compose.
• Dosarele tale media sau un loc unde să le creezi. Citește mai întâi Dosare dacă vrei mutări instantanee în loc de copii.
• Pe un NAS, Unraid sau Synology, vezi NAS, Synology și Unraid. Fără Docker, vezi Versiunea portabilă.

Pași

1. Creează un dosar pentru configurare pe un disc local, de exemplu /srv/holyarrs/config. Nu un dosar partajat în rețea. În Docker Desktop, folosește în schimb un volum cu nume. Vezi Docker Desktop.

2. Află utilizatorul și grupul care dețin dosarele tale media:

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

   Folosește uid ca PUID și gid ca PGID.

3. Salvează asta ca docker-compose.yml și schimbă căile:

   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. Pornește-l:

   docker compose up -d
   docker compose ps

   Containerul apare ca healthy (sănătos) imediat ce HolyArrs răspunde.

5. Deschide http://your-server:6262 și creează imediat contul proprietarului. Nu există nicio parolă implicită. Până îl creezi, cine deschide primul HolyArrs devine proprietar.

6. Urmează configurarea care se deschide apoi. Vezi Prima pornire.

Atenție

Nu există nicio parolă implicită. Cine deschide primul un HolyArrs nou devine proprietar. Creează contul acum.

Dacă preferi 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

Eticheta imaginii

Etichetă	Ce primești
latest	Cea mai nouă versiune
1.0.0 (orice versiune)	Exact acea versiune, nu se schimbă niciodată

Setările explicate

Porturi și dosare

Setare	Ce face
-p 6262:6262	Aplicația web.
-v /config	Bazele de date, setările, cheia principală, copiile de rezervă și jurnalele. Doar disc local.
-v /movies	Opțional. Un dosar al Bibliotecii pentru filme.
-v /tv	Opțional. Un dosar al Bibliotecii pentru seriale.
-v /music	Opțional. Un dosar al Bibliotecii pentru muzică.
-v /downloads	Opțional. Dosarul de descărcare al programului de descărcare. Vezi Dosare media.
--read-only=true	Opțional. Vezi Sistem de fișiere root doar în citire.
--user=1000:1000	Opțional. Vezi Pornire cu un utilizator fix.

Variabile de mediu

Variabilă	Ce face
PUID, PGID	Utilizatorul și grupul cu care rulează HolyArrs. 1000 și 1000 dacă le omiți.
TZ	Fus orar, de exemplu Europe/Amsterdam.
UMASK	Opțional. Ce biți de permisiune lasă deoparte fișierele noi, de exemplu 022 sau 002.
HOLYARRS_SAVE_PATH	Opțional. Dosarul în care salvează programul de descărcare, așa cum îl vede el.
HOLYARRS_ALLOWED_HOSTS	Opțional. Nume de gazdă în plus cu care oamenii ajung la HolyArrs, separate prin virgulă.
HOLYARRS_TRUSTED_PROXIES	Opțional. Adresa sau rețeaua proxy-ului tău invers.
HOLYARRS_URL_BASE	Opțional. Servește HolyArrs sub o cale. Vezi Proxy invers și URL base.
HOLYARRS_MASTER_KEY_FILE	Opțional. Citește cheia principală dintr-un fișier separat.

Orice variabilă poate veni dintr-un fișier. Pune FILE__ în fața numelui și dă calea fișierului ca valoare:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Se elimină o singură linie nouă de la sfârșitul fișierului. Merge și pentru PUID, PGID, UMASK și TZ. Dacă fișierul lipsește, HolyArrs se oprește și numește variabila în jurnal (log). Nu afișează niciodată valoarea.

Imaginea

Imaginea conține HolyArrs și foarte puțin altceva. Nu are shell, deci nu poți face docker exec în ea ca să te uiți prin ea. Citește în schimb jurnalul cu docker logs holyarrs sau deschide logs/holyarrs.log din dosarul de configurare.

Comenzile proprii ale HolyArrs merg în continuare prin docker exec:

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

Imaginile sunt construite pentru amd64, ARM pe 64 de biți și ARM pe 32 de biți. Pe un aparat cu cam 2.5 GiB de memorie sau mai puțin, HolyArrs pornește singur modul cu memorie puțină. Prima linie din jurnal spune asta.

Utilizator și grup

Containerul pornește ca root doar ca să se configureze. Dă dosarul de configurare lui PUID:PGID când e nevoie, apoi trece definitiv la acel utilizator. Prima linie din jurnal arată utilizatorul, grupul și umask-ul.

HolyArrs nu schimbă niciodată proprietarul dosarelor tale media sau de descărcare. Dă tu utilizatorului PUID permisiune de scriere în ele. Accesul de citire nu ajunge, pentru că HolyArrs creează dosare și mută fișiere.

Unele tipuri de stocare nu pot schimba proprietarii, cum ar fi NFS cu root squash, SMB sau o montare doar în citire. HolyArrs scrie atunci un avertisment și merge mai departe. Dă manual drept de scriere pe dosarul de configurare pentru PUID:PGID.

Schimbarea utilizatorului cere capabilitățile CHOWN, DAC_OVERRIDE, SETUID și SETGID. Docker le dă implicit. Dacă le elimini, HolyArrs se oprește cu un mesaj. Nu revine la root. Ca să rulezi cu adevărat ca root, setează PUID=0 și PGID=0.

Grupurile în plus din group_add: se păstrează când HolyArrs schimbă utilizatorul.

UMASK afectează doar fișierele noi. Omite-l ca să păstrezi 022, unde scrii tu, iar ceilalți citesc. Folosește 002 când și un grup trebuie să scrie.

Dosare media

Montează doar dosarele pe care le folosești: /movies, /tv și /music ca dosare ale Bibliotecii și /downloads ca dosar de descărcare.

Sfat pentru hardlink-uri (legături fizice): fiecare dosar montat separat este o montare distinctă în interiorul containerului, iar un fișier nu poate fi legat fizic între montări, așa că importurile devin copii complete. Dacă vrei hardlink-uri, poți monta în schimb un singur dosar părinte comun (cu dosarele de descărcări și ale Bibliotecii înăuntru) în locul celor patru montări opționale și să dai programului de descărcare aceeași montare pe aceeași cale. Dosarul părinte trebuie să fie și un singur sistem de fișiere. Dosarele partajate sau dataset-urile NAS separate din el tot se copiază. Settings (Setări) > Library folders (dosarele Bibliotecii) te avertizează când HolyArrs trebuie să copieze.

HOLYARRS_SAVE_PATH se trimite programului de descărcare la fiecare descărcare, deci schimbă și locul unde salvează acesta. Omite-l ca să păstrezi setarea proprie a programului de descărcare. Dacă îl omiți, adaugă dosarul de descărcări la Settings > Library folders > Extra import folders, ca să poți importa manual din el.

Păstrează cheia principală

HolyArrs criptează parolele, cheile și token-urile salvate cu o cheie principală. La prima pornire creează /config/holyarrs.key.

Copiile de rezervă nu conțin niciodată această cheie. Păstrează o copie în altă parte. Varianta ușoară: ca proprietar, deschide Settings > Backups și alege Download key kit (descarcă pachetul cu cheia). Ca s-o readuci, numește fișierul holyarrs.key și pune-l în dosarul de configurare cât timp HolyArrs este oprit. O restaurare cu altă cheie este refuzată. Cu un volum cu nume nu există un dosar de deschis: copiază-o înăuntru cu docker cp holyarrs.key hx:/config/, ca în Docker Desktop. Te muți pe un aparat nou? Readu mai întâi cheia, apoi restaurează copia de rezervă. Vezi Copii de rezervă.

Poți păstra cheia și într-un fișier separat, doar în citire:

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

Fișierul trebuie să existe și să conțină 32 de octeți bruți, 64 de cifre hex sau base64 pentru 32 de octeți. Utilizatorul PUID trebuie să-l poată citi.

Repornire și restaurare

Păstrează o politică de repornire. O restaurare este verificată și pregătită, apoi HolyArrs iese cu codul 75, ca Docker să-l pornească din nou și să o aplice. unless-stopped se ocupă de asta.

Ca să actualizezi o versiune construită local, reconstruiește și recreează fără să atingi montările:

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

Nu șterge niciodată /config în timpul unei actualizări. Vezi Actualizări și Copii de rezervă.

Nume de gazdă și proxy-uri inverse

Adresele IP și localhost merg direct. Un nume de acasă, cum ar fi tower.local, pe care îl folosești la prima configurare, este salvat pentru tine. Adaugă alte nume la Allowed host names (nume de gazdă permise) în Settings > Sign-in and security, sau în HOLYARRS_ALLOWED_HOSTS.

Când un proxy invers adaugă X-Forwarded-For, pune în HOLYARRS_TRUSTED_PROXIES doar adresa sau rețeaua proxy-ului. Fără asta, autentificarea unică (SSO), adresele reale ale clienților și cookie-ul Secure nu funcționează, iar toți cei din spatele proxy-ului împart o singură limită de conectare. Jurnalul spune ce adresă de proxy să adaugi. Dacă în față mai e un proxy, cum ar fi Cloudflare, adaugă și intervalele lui.

Cu nginx, trimite ambele antete:

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

Dacă cele două nu se potrivesc, HolyArrs tratează vizitatorul ca fiind din afara rețelei tale.

Bazele securității

• Nu redirecționa portul 6262 pe router. Folosește un VPN, cum ar fi Tailscale, sau un proxy invers cu HTTPS.
• Creează contul proprietarului imediat după prima pornire.
• Păstrează o copie a cheii principale departe de dosarul de configurare.
• Ține imaginea la zi.

Configurări speciale

Docker Desktop (Windows și Mac)

Docker Desktop partajează dosarele gazdei printr-un strat în care blocările de fișiere ale bazelor de date nu sunt sigure. HolyArrs refuză un /config de acolo și arată soluția pe portul 6262. Folosește un volum cu nume pentru /config. Dosarele media pot rămâne dosare ale gazdei.

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:

Ca să muți un dosar de configurare vechi în volum, oprește HolyArrs și rulează:

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

Ca să scoți copiile de rezervă: docker cp holyarrs:/config/backups .

Pe un Mac, dacă ai verificat că blocările de fișiere merg în dosarul tău, setează HOLYARRS_ALLOW_DESKTOP_FOLDER=1 ca să pornească oricum. HolyArrs te avertizează la fiecare pornire. Asta nu ridică niciodată refuzul pentru dosarele partajate în rețea.

Sistem de fișiere root doar în citire

Doar /config și /tmp trebuie să permită scrierea:

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

PUID, PGID și UMASK merg în continuare.

Pornire cu un utilizator fix

services:
  holyarrs:
    user: "1000:1000"

HolyArrs nu mai schimbă atunci niciun proprietar, deci dosarul de configurare trebuie să fie deja cu drept de scriere pentru acel utilizator. PUID și PGID sunt ignorate, iar jurnalul spune asta. Asta acoperă și runAsUser din Kubernetes.

Docker rootless și Podman

În modul rootless, root-ul din container este propriul tău utilizator, iar celelalte id-uri se mapează la numere mari pe gazdă. Cu PUID=1000, dosarul de configurare ajunge să aparțină unui străin pe gazdă.

Ce rulezi	docker info sau podman info arată	Folosește
Docker normal	fără rootless	PUID și PGID ca de obicei
Docker rootless	rootless la Security Options	Opțiunea 1
Podman rootless	rootless: true	Opțiunea 1 sau 2

Opțiunea 1. Setează PUID=0 și PGID=0. E sigur doar în modul rootless. Nu face asta niciodată cu Docker normal sau pe un NAS.

Opțiunea 2. Podman cu keep-id, ca Quadlet în ~/.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

Sau ca o singură comandă:

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 este pentru sistemele cu SELinux. Folosește :z pe dosarele pe care le împarte programul de descărcare. Nu folosi niciunul pe un dosar partajat în rețea (NFS sau SMB): nu poate fi reetichetat, iar containerul nu ar porni.
• Dă verificarea de sănătate ca listă. Imaginea nu are shell.
• Păstrează politica de repornire always. Serviciul Podman de pornire după repornire pornește doar containerele always.
• Ca să pornească după o repornire fără să te conectezi, rulează o dată loginctl enable-linger $USER. Apoi folosește fișierul Quadlet sau, pentru podman run, rulează systemctl --user enable podman-restart.service.

Dacă dosarul aparține deja unui id mare, oprește mai întâi containerul, apoi:

• Podman rootless: podman unshare chown -R 0:0 ~/holyarrs/config (Opțiunea 1) sau podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Docker rootless: rootlesskit chown -R 0:0 ~/holyarrs/config, rulat prin nsenter în daemonul rootless (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Construiește-ți propria imagine

Din checkout-ul HolyArrs:

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

Apoi folosește holyarrs:local ca imagine.

Depanare

Rulează mai întâi doctor. Verifică configurarea, dosarele, rețeaua și ceasul și îți spune cum să rezolvi fiecare problemă.

• Container pornit: docker exec holyarrs /holyarrs doctor
• Containerul repornește mereu: docker compose run --rm holyarrs doctor

Vezi Depanare pentru jurnal și pachetul de suport.

Vezi	Fă asta
Config folder is on a shared or network folder (dosarul de configurare e pe un dosar partajat sau de rețea)	Folosește un disc local sau un volum cu nume în Docker Desktop. Pe Unraid folosește /mnt/<pool>/appdata/holyarrs.
Config folder is in memory (dosarul de configurare e în memorie)	Pune /config pe un disc. Pe Unraid, verifică dacă există calea pool-ului. Pentru un aparat de test, HOLYARRS_CONFIG_IN_MEMORY=yes o permite.
Config folder cannot be written (în dosarul de configurare nu se poate scrie)	Elimină :ro și verifică dacă PUID:PGID dețin dosarul.
Disk is full (discul e plin)	Eliberează spațiu pe discul care conține /config, apoi repornește.
/config is not mapped (nu e mapat)	Vezi mai jos.
Cannot switch user (nu se poate schimba utilizatorul)	Adaugă la loc cele patru capabilități sau folosește user: "<uid>:<gid>".
PUID/PGID does not exist inside this container (PUID/PGID nu există în acest container)	Id-urile sunt în afara intervalului mapat. Vezi Docker rootless și Podman.
O variabilă FILE__ nu poate fi citită	Verifică calea și dacă fișierul este montat.
Permission denied (permisiune refuzată)	Verifică PUID, PGID și permisiunea de scriere pe toate dosarele.
Unknown host name (nume de gazdă necunoscut)	Deschide HolyArrs după IP și adaugă numele la Allowed host names.
Importurile sunt copiate	Montează un singur dosar comun. Vezi Dosare media.
Master key does not match (cheia principală nu se potrivește)	Readu cheia care aparține acelor baze de date.
Restore staged but the app stays down (restaurare pregătită, dar aplicația rămâne oprită)	Adaugă o politică de repornire și pornește containerul.

Ai uitat să mapezi /config?

HolyArrs tot pornește, dar avertizează peste tot. Totul se pierde când containerul este șters. Salvează mai întâi:

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

Apoi mapează ./holyarrs-config:/config (sau un volum cu nume) și recreează containerul. În Docker Desktop (Windows și Mac), folosește un volum cu nume, nu un dosar al gazdei, și copiază datele înăuntru cum se arată în Docker Desktop. O configurare mai veche poate fi încă într-un volum fără nume. Le listezi cu docker volume ls.

Vezi și

• Dosare
• Prima pornire
• NAS, Synology și Unraid
• Actualizări