Instal·lació

Executa HolyArrs a Docker i obre’l al navegador. Hi tardaràs uns minuts.

Abans de començar

• Un equip amb Docker i Docker Compose.
• Les teves carpetes multimèdia, o un lloc on crear-les. Llegeix primer Carpetes si vols que els fitxers es moguin a l’instant en lloc de copiar-se.
• En un NAS, Unraid o Synology, mira NAS, Synology i Unraid. Sense Docker, mira Versió portàtil.

Passos

1. Crea una carpeta per a la configuració en un disc local, per exemple /srv/holyarrs/config. No una carpeta compartida de xarxa. A Docker Desktop, fes servir un volum amb nom. Mira Docker Desktop.

2. Troba l’usuari i el grup propietaris de les teves carpetes multimèdia:

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

   Fes servir el uid com a PUID i el gid com a PGID.

3. Desa això com a docker-compose.yml i canvia les rutes:

   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. Inicia’l:

   docker compose up -d
   docker compose ps

   El contenidor apareix com a healthy quan HolyArrs respon.

5. Obre http://your-server:6262 i crea el compte de propietari de seguida. No hi ha cap contrasenya per defecte. Fins que el creïs, qui obri HolyArrs primer es converteix en el propietari.

6. Segueix la configuració que s’obre a continuació. Mira Primer inici.

Precaució

No hi ha cap contrasenya per defecte. Qui obri primer un HolyArrs nou es converteix en el propietari. Crea el compte ara.

Si prefereixes 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

Etiqueta de la imatge

Etiqueta	Què obtens
latest	La versió més nova
1.0.0 (qualsevol versió)	Exactament aquesta versió, no canvia mai

Paràmetres explicats

Ports i carpetes

Paràmetre	Què fa
-p 6262:6262	L’app web.
-v /config	Bases de dades, paràmetres, la clau mestra, còpies de seguretat i registres. Només disc local.
-v /movies	Opcional. Una carpeta de la Biblioteca per a pel·lícules.
-v /tv	Opcional. Una carpeta de la Biblioteca per a sèries.
-v /music	Opcional. Una carpeta de la Biblioteca per a música.
-v /downloads	Opcional. La carpeta de baixades del gestor de baixades. Mira Carpetes multimèdia.
--read-only=true	Opcional. Mira Sistema de fitxers arrel de només lectura.
--user=1000:1000	Opcional. Mira Iniciar com a usuari fix.

Variables d’entorn

Variable	Què fa
PUID, PGID	L’usuari i el grup amb què s’executa HolyArrs. 1000 i 1000 si ho omets.
TZ	Fus horari, per exemple Europe/Amsterdam.
UMASK	Opcional. Quins bits de permís deixen fora els fitxers nous, per exemple 022 o 002.
HOLYARRS_SAVE_PATH	Opcional. La carpeta on desa el gestor de baixades, tal com la veu ell.
HOLYARRS_ALLOWED_HOSTS	Opcional. Noms de host addicionals que la gent fa servir per arribar a HolyArrs, separats per comes.
HOLYARRS_TRUSTED_PROXIES	Opcional. L’adreça o la xarxa del teu reverse proxy.
HOLYARRS_URL_BASE	Opcional. Serveix HolyArrs sota una ruta. Mira URL base i reverse proxies.
HOLYARRS_MASTER_KEY_FILE	Opcional. Llegeix la clau mestra d’un fitxer propi.

Qualsevol variable pot venir d’un fitxer. Posa FILE__ davant del nom i dona la ruta del fitxer com a valor:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

S’elimina un sol salt de línia al final del fitxer. Això també funciona per a PUID, PGID, UMASK i TZ. Si falta el fitxer, HolyArrs s’atura i posa el nom de la variable al registre (log). Mai en mostra el valor.

La imatge

La imatge conté HolyArrs i poca cosa més. No té shell, així que no pots fer docker exec a dins per mirar-hi. Llegeix-ne el registre amb docker logs holyarrs, o obre logs/holyarrs.log a la carpeta de configuració.

Les ordres pròpies d’HolyArrs continuen funcionant amb docker exec:

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

Les imatges es creen per a amd64, ARM de 64 bits i ARM de 32 bits. En un equip amb uns 2.5 GiB de memòria o menys, HolyArrs activa per si sol el mode de poca memòria. La primera línia del registre ho diu.

Usuari i grup

El contenidor s’inicia com a root només per configurar-se. Fa que PUID:PGID sigui propietari de la carpeta de configuració quan cal, i després canvia a aquest usuari per sempre. La primera línia del registre mostra l’usuari, el grup i la umask.

HolyArrs mai canvia el propietari de les teves carpetes multimèdia ni de baixades. Dona tu mateix permís d’escriptura a l’usuari PUID. El permís de lectura no és suficient, perquè HolyArrs crea carpetes i mou fitxers.

Alguns emmagatzematges no poden canviar de propietari, com NFS amb root squash, SMB o un muntatge de només lectura. HolyArrs llavors registra una advertència i continua. Fes que la carpeta de configuració sigui escrivible per a PUID:PGID a mà.

Canviar d’usuari necessita les capacitats CHOWN, DAC_OVERRIDE, SETUID i SETGID. Docker les dona per defecte. Si les treus, HolyArrs s’atura amb un missatge. No torna a root. Per executar-lo realment com a root, posa PUID=0 i PGID=0.

Els grups addicionals de group_add: es mantenen quan HolyArrs canvia d’usuari.

UMASK només afecta els fitxers nous. Omet-ho per mantenir 022, on tu escrius i els altres llegeixen. Fes servir 002 quan un grup també ha d’escriure.

Carpetes multimèdia

Munta només les carpetes que facis servir: /movies, /tv i /music com a carpetes de la Biblioteca i /downloads com a carpeta de baixades.

Consell per als hardlinks (enllaç dur): cada carpeta que muntes per separat és un muntatge diferent dins del contenidor, i un fitxer no es pot enllaçar amb hardlink entre muntatges, així que les importacions es converteixen en còpies completes. Si vols hardlinks, pots muntar una sola carpeta mare compartida (amb les baixades i les carpetes de la Biblioteca a dins) en lloc dels quatre muntatges opcionals, i donar al gestor de baixades el mateix muntatge a la mateixa ruta. La carpeta mare també ha de ser un sol sistema de fitxers. Les carpetes compartides o conjunts de dades de NAS separats a dins continuen copiant. Settings (Paràmetres) > Library folders (carpetes de la Biblioteca) t’avisa quan HolyArrs ha de copiar.

HOLYARRS_SAVE_PATH s’envia al gestor de baixades amb cada baixada, així que també canvia on desa el gestor de baixades. Omet-ho per mantenir el paràmetre propi del gestor de baixades. Si l’omets, afegeix la carpeta de baixades a Settings > Library folders > Extra import folders (carpetes d’importació addicionals) per poder importar-hi a mà.

Guarda la clau mestra

HolyArrs xifra les contrasenyes, claus i tokens desats amb una clau mestra. El primer inici crea /config/holyarrs.key.

Les còpies de seguretat mai contenen aquesta clau. Guarda’n una còpia en un altre lloc. La manera fàcil: com a propietari, obre Settings > Backups (còpies de seguretat) i tria Download key kit (baixa el kit de claus). Per tornar-la a posar, anomena el fitxer holyarrs.key i deixa’l a la carpeta de configuració mentre HolyArrs està aturat. Una restauració amb una clau diferent es rebutja. Amb un volum amb nom no hi ha cap carpeta per obrir: copia-la a dins amb docker cp holyarrs.key hx:/config/ com es mostra a Docker Desktop. Canvies a un equip nou? Posa primer la clau al lloc, i després restaura la còpia de seguretat. Mira Còpies de seguretat.

També pots guardar la clau en un fitxer propi de només lectura:

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

El fitxer ha d’existir i contenir 32 bytes en brut, 64 dígits hexadecimals o base64 de 32 bytes. L’usuari PUID l’ha de poder llegir.

Reinici i restauració

Mantén una política de reinici. Una restauració es comprova i es prepara, i després HolyArrs surt amb l’estat 75 perquè Docker l’iniciï de nou i l’apliqui. unless-stopped ho gestiona.

Per actualitzar una compilació local, torna-la a compilar i recrea el contenidor sense tocar els muntatges:

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

No eliminis mai /config durant una actualització. Mira Actualitzacions i Còpies de seguretat.

Noms de host i reverse proxies

Les adreces IP i localhost funcionen sense fer res. Un nom de casa com tower.local que facis servir durant la primera configuració es desa automàticament. Afegeix altres noms a Allowed host names (noms de host permesos) a Settings > Sign-in and security (inici de sessió i seguretat), o a HOLYARRS_ALLOWED_HOSTS.

Quan un reverse proxy afegeix X-Forwarded-For, posa a HOLYARRS_TRUSTED_PROXIES només l’adreça o la xarxa del proxy. Sense això, l’inici de sessió únic, les adreces reals dels clients i la cookie Secure no funcionen, i tothom darrere del proxy comparteix un sol límit d’inicis de sessió. El registre indica l’adreça del proxy que has d’afegir. Si al davant hi ha un altre proxy, com Cloudflare, afegeix-ne també els intervals.

Amb nginx, envia les dues capçaleres:

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

Si les dues no coincideixen, HolyArrs tracta el visitant com a extern a la teva xarxa.

Seguretat bàsica

• No reenviïs el port 6262 al router. Fes servir una VPN com Tailscale, o un reverse proxy amb HTTPS.
• Crea el compte de propietari just després del primer inici.
• Guarda una còpia de la clau mestra lluny de la carpeta de configuració.
• Mantén la imatge actualitzada.

Configuracions especials

Docker Desktop (Windows i Mac)

Docker Desktop comparteix les carpetes de l’equip a través d’una capa on els bloquejos de fitxers de la base de dades no són segurs. HolyArrs rebutja un /config allà i mostra la solució al port 6262. Fes servir un volum amb nom per a /config. Les carpetes multimèdia poden continuar sent carpetes de l’equip.

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:

Per moure una carpeta de configuració antiga al volum, atura HolyArrs i executa:

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

Per treure’n les còpies de seguretat: docker cp holyarrs:/config/backups .

En un Mac, si has comprovat que els bloquejos de fitxers funcionen a la teva carpeta, posa HOLYARRS_ALLOW_DESKTOP_FOLDER=1 per iniciar igualment. HolyArrs avisa a cada inici. Això mai fa que s’acceptin les carpetes compartides de xarxa.

Sistema de fitxers arrel de només lectura

Només /config i /tmp han de ser escrivibles:

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

PUID, PGID i UMASK continuen funcionant.

Iniciar com a usuari fix

services:
  holyarrs:
    user: "1000:1000"

HolyArrs llavors no canvia cap propietari, així que la carpeta de configuració ja ha de ser escrivible per a aquest usuari. PUID i PGID s’ignoren i el registre ho diu. Això també cobreix runAsUser de Kubernetes.

Docker rootless i Podman

En mode rootless, root dins del contenidor és el teu propi usuari, i els altres id s’assignen a números alts a l’equip. Amb PUID=1000, la carpeta de configuració acaba sent d’un desconegut a l’equip.

Què executes	docker info o podman info mostra	Fes servir
Docker normal	cap rootless	PUID i PGID com sempre
Docker rootless	rootless a Security Options	Opció 1
Podman rootless	rootless: true	Opció 1 o 2

Opció 1. Posa PUID=0 i PGID=0. Això només és segur en mode rootless. No ho facis mai amb Docker normal ni en un NAS.

Opció 2. Podman amb keep-id, com a Quadlet a ~/.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

O amb una sola ordre:

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 és per a sistemes amb SELinux. Fes servir :z en carpetes que comparteixi el gestor de baixades. No facis servir cap de les dues en una carpeta compartida de xarxa (NFS o SMB): no es pot reetiquetar i el contenidor no s’iniciaria.
• Escriu la comprovació de salut com a llista. La imatge no té shell.
• Mantén la política de reinici always. El servei de Podman per iniciar després d’un reinici només inicia contenidors always.
• Per iniciar després d’un reinici sense iniciar la sessió, executa loginctl enable-linger $USER una vegada. Després fes servir el fitxer Quadlet, o per a podman run executa systemctl --user enable podman-restart.service.

Si la carpeta ja pertany a un id alt, atura primer el contenidor i després:

• Podman rootless: podman unshare chown -R 0:0 ~/holyarrs/config (Opció 1) o podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Docker rootless: rootlesskit chown -R 0:0 ~/holyarrs/config, executat a través de nsenter dins del dimoni rootless (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Crea la teva pròpia imatge

Des del checkout d’HolyArrs:

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

Després fes servir holyarrs:local com a imatge.

Resolució de problemes

Executa primer el doctor. Comprova la configuració, les carpetes, la xarxa i el rellotge, i t’explica com arreglar cada problema.

• Contenidor en execució: docker exec holyarrs /holyarrs doctor
• El contenidor es reinicia constantment: docker compose run --rm holyarrs doctor

Mira Resolució de problemes per al registre i el paquet de suport.

Què veus	Què has de fer
Config folder is on a shared or network folder	Fes servir un disc local, o un volum amb nom a Docker Desktop. A Unraid fes servir /mnt/<pool>/appdata/holyarrs.
Config folder is in memory	Posa /config en un disc. A Unraid, comprova que la ruta del pool existeix. Per a un equip de proves, HOLYARRS_CONFIG_IN_MEMORY=yes ho permet.
Config folder cannot be written	Treu :ro i comprova que PUID:PGID són propietaris de la carpeta.
Disk is full	Allibera espai al disc que conté /config i reinicia.
/config is not mapped	Mira a sota.
Cannot switch user	Torna a afegir les quatre capacitats, o fes servir user: "<uid>:<gid>".
PUID/PGID does not exist inside this container	Els id són fora de l’interval mapat. Mira Docker rootless i Podman.
A FILE__ variable cannot be read	Comprova la ruta i que el fitxer estigui muntat.
Permission denied	Comprova PUID, PGID i el permís d’escriptura a totes les carpetes.
Unknown host name	Obre HolyArrs per IP i afegeix el nom a Allowed host names.
Imports are copied	Munta una carpeta compartida. Mira Carpetes multimèdia.
Master key does not match	Torna a posar la clau que correspon a aquestes bases de dades.
Restore staged but the app stays down	Afegeix una política de reinici i inicia el contenidor.

Has oblidat mapar /config?

HolyArrs s’inicia igualment, però avisa a tot arreu. Es perd tot quan el contenidor s’elimina. Desa-ho primer:

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

Després mapa ./holyarrs-config:/config (o un volum amb nom) i recrea el contenidor. A Docker Desktop (Windows i Mac), fes servir un volum amb nom, no una carpeta de l’equip, i copia-hi les dades com es mostra a Docker Desktop. Una configuració anterior pot continuar en un volum sense nom. Llista’ls amb docker volume ls.

Relacionat

• Carpetes
• Primer inici
• NAS, Synology i Unraid
• Actualitzacions