Installazione

Esegui HolyArrs in Docker e aprilo nel browser. Ci vogliono pochi minuti.

Prima di iniziare

• Un computer con Docker e Docker Compose.
• Le tue cartelle multimediali, o un posto dove crearle. Leggi prima Cartelle se vuoi spostamenti istantanei invece di copie.
• Su un NAS, Unraid o Synology, vedi NAS, Synology e Unraid. Senza Docker, vedi Archivi portatili.

Passaggi

1. Crea una cartella per la configurazione su un disco locale, per esempio /srv/holyarrs/config. Non una condivisione di rete. Su Docker Desktop usa invece un volume con nome. Vedi Docker Desktop.

2. Trova l’utente e il gruppo proprietari delle tue cartelle multimediali:

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

   Usa uid come PUID e gid come PGID.

3. Salva questo come docker-compose.yml e cambia i percorsi:

   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. Avvialo:

   docker compose up -d
   docker compose ps

   Il container risulta integro (healthy) quando HolyArrs risponde.

5. Apri http://your-server:6262 e crea subito l’account del Proprietario. Non esiste una password predefinita. Finché non lo crei, chiunque apra HolyArrs per primo diventa il Proprietario.

6. Segui la configurazione che si apre subito dopo. Vedi Primo avvio.

Attenzione

Non esiste una password predefinita. Chiunque apra per primo un HolyArrs nuovo diventa il Proprietario. Crea l’account adesso.

Se preferisci 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 dell’immagine

Tag	Cosa ottieni
latest	L’ultima versione
1.0.2 (qualsiasi versione)	Esattamente quella versione, non cambia mai

Impostazioni spiegate

Porte e cartelle

Impostazione	Cosa fa
-p 6262:6262	L’app web.
-v /config	Database, impostazioni, la chiave principale, backup e log. Solo disco locale.
-v /movies	Facoltativo. Una cartella della Libreria per i film.
-v /tv	Facoltativo. Una cartella della Libreria per le serie.
-v /music	Facoltativo. Una cartella della Libreria per la musica.
-v /downloads	Facoltativo. La cartella dei download del downloader. Vedi Cartelle multimediali.
--read-only=true	Facoltativo. Vedi Filesystem root in sola lettura.
--user=1000:1000	Facoltativo. Vedi Avvio con un utente fisso.

Variabili d’ambiente

Variabile	Cosa fa
PUID, PGID	L’utente e il gruppo con cui gira HolyArrs. 1000 e 1000 se li ometti.
TZ	Fuso orario, per esempio Europe/Amsterdam.
UMASK	Facoltativo. Quali bit di permesso i nuovi file lasciano fuori, per esempio 022 o 002.
HOLYARRS_SAVE_PATH	Facoltativo. La cartella di salvataggio del downloader, come la vede il downloader.
HOLYARRS_ALLOWED_HOSTS	Facoltativo. Nomi host aggiuntivi che le persone usano per raggiungere HolyArrs, separati da virgole.
HOLYARRS_TRUSTED_PROXIES	Facoltativo. L’indirizzo o la rete del tuo reverse proxy.
HOLYARRS_URL_BASE	Facoltativo. Pubblica HolyArrs sotto un percorso. Vedi URL base e reverse proxy.
HOLYARRS_MASTER_KEY_FILE	Facoltativo. Legge la chiave principale da un file a parte.

Ogni variabile può arrivare da un file. Metti FILE__ davanti al nome e dai come valore il percorso del file:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Un solo a capo alla fine del file viene scartato. Vale anche per PUID, PGID, UMASK e TZ. Se il file manca, HolyArrs si ferma e scrive nel log il nome della variabile. Non stampa mai il valore.

L’immagine

L’immagine contiene HolyArrs e poco altro. Non ha una shell, quindi non puoi entrarci con docker exec per guardarti intorno. Leggi invece il log con docker logs holyarrs, oppure apri logs/holyarrs.log nella cartella di configurazione.

I comandi di HolyArrs funzionano comunque con docker exec:

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

Le immagini sono create per amd64, ARM a 64 bit e ARM a 32 bit. Su un computer con circa 2.5 GiB di memoria o meno, HolyArrs attiva da solo la modalità a basso consumo di memoria. Lo dice la prima riga del log.

Utente e gruppo

Il container parte come root solo per prepararsi. Quando serve, assegna la cartella di configurazione a PUID:PGID, poi passa a quell’utente per sempre. La prima riga del log mostra utente, gruppo e umask.

HolyArrs non cambia mai il proprietario delle tue cartelle multimediali o dei download. Dai tu all’utente PUID il permesso di scrittura. Il solo permesso di lettura non basta, perché HolyArrs crea cartelle e sposta file.

Alcuni sistemi di archiviazione non possono cambiare proprietario, come NFS con root squash, SMB o un mount in sola lettura. In quel caso HolyArrs scrive un’avvertenza nel log e va avanti. Rendi la cartella di configurazione scrivibile per PUID:PGID a mano.

Il cambio di utente richiede le capability CHOWN, DAC_OVERRIDE, SETUID e SETGID. Docker le dà per impostazione predefinita. Se le togli, HolyArrs si ferma con un messaggio. Non ripiega su root. Per girare davvero come root, imposta PUID=0 e PGID=0.

I gruppi aggiuntivi di group_add: restano quando HolyArrs cambia utente.

UMASK riguarda solo i nuovi file. Omettilo per tenere 022, dove tu scrivi e gli altri leggono. Usa 002 quando deve poter scrivere anche un gruppo.

Cartelle multimediali

Monta solo le cartelle che usi: /movies, /tv e /music come cartelle della Libreria e /downloads come cartella dei download.

Suggerimento per gli hardlink (collegamenti fisici): ogni cartella montata da sola è un mount separato dentro il container, e un file non può avere un hardlink tra mount diversi, quindi le importazioni diventano copie complete. Se vuoi gli hardlink, puoi invece montare una sola cartella madre condivisa (con dentro download e cartelle della Libreria) al posto dei quattro mount facoltativi, e dare al downloader lo stesso mount allo stesso percorso. La cartella madre deve stare anche su un solo filesystem. Condivisioni NAS o dataset separati al suo interno fanno comunque copie. Settings > Library folders ti avvisa quando HolyArrs deve copiare.

HOLYARRS_SAVE_PATH viene inviato al downloader a ogni download, quindi cambia anche dove il downloader salva. Omettilo per tenere l’impostazione del downloader. Se lo ometti, aggiungi la cartella dei download in Settings > Library folders > Extra import folders, così puoi importare a mano da lì.

Conserva la chiave principale

HolyArrs cifra password, chiavi e token salvati con una chiave principale. Il primo avvio crea /config/holyarrs.key.

I backup non contengono mai questa chiave. Conserva una copia altrove. Il modo facile: da Proprietario, apri Settings > Backups e scegli Download key kit (scarica il kit della chiave). Per ripristinarla, dai al file il nome holyarrs.key e mettilo nella cartella di configurazione mentre HolyArrs è fermo. Un ripristino con una chiave diversa viene rifiutato. Con un volume con nome non c’è nessuna cartella da aprire: copialo dentro con docker cp holyarrs.key hx:/config/ come in Docker Desktop. Stai passando a un nuovo computer? Ripristina prima la chiave, poi il backup. Vedi Backup.

Puoi anche tenere la chiave in un file a parte, in sola lettura:

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

Il file deve esistere e contenere 32 byte grezzi, 64 cifre esadecimali o base64 per 32 byte. L’utente PUID deve poterlo leggere.

Riavvio e ripristino

Tieni un criterio di riavvio. Un ripristino viene controllato e preparato, poi HolyArrs esce con stato 75 così Docker lo riavvia e lo applica. unless-stopped va bene.

Per aggiornare una build locale, ricostruisci e ricrea senza toccare i mount:

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

Non rimuovere mai /config durante un aggiornamento. Vedi Aggiornamenti e Backup.

Nomi host e reverse proxy

Gli indirizzi IP e localhost funzionano subito. Un nome di casa come tower.local che usi durante la prima configurazione viene salvato per te. Aggiungi altri nomi sotto Allowed host names (nomi host consentiti) in Settings > Sign-in and security, oppure in HOLYARRS_ALLOWED_HOSTS.

Quando un reverse proxy aggiunge X-Forwarded-For, metti in HOLYARRS_TRUSTED_PROXIES solo l’indirizzo o la rete del proxy. Senza, l’accesso singolo, gli indirizzi reali dei client e il cookie Secure non funzionano, e tutti quelli dietro il proxy condividono un solo limite di accessi. Il log indica l’indirizzo del proxy da aggiungere. Se un altro proxy sta davanti, come Cloudflare, aggiungi anche i suoi intervalli.

Con nginx, invia entrambi gli header:

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

Se i due non coincidono, HolyArrs considera il visitatore fuori dalla tua rete.

Basi di sicurezza

• Non inoltrare la porta 6262 sul router. Usa una VPN come Tailscale, oppure un reverse proxy con HTTPS.
• Crea l’account del Proprietario subito dopo il primo avvio.
• Tieni una copia della chiave principale lontano dalla cartella di configurazione.
• Tieni l’immagine aggiornata.

Configurazioni particolari

Docker Desktop (Windows e Mac)

Docker Desktop condivide le cartelle dell’host attraverso un livello in cui i blocchi dei file dei database non sono sicuri. HolyArrs rifiuta un /config lì e mostra la soluzione sulla porta 6262. Usa un volume con nome per /config. Le cartelle multimediali possono restare cartelle dell’host.

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 spostare una vecchia cartella di configurazione nel volume, ferma HolyArrs ed esegui:

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

Per copiare i backup fuori: docker cp holyarrs:/config/backups .

Su un Mac, se hai verificato che i blocchi dei file funzionano nella tua cartella, imposta HOLYARRS_ALLOW_DESKTOP_FOLDER=1 per avviare comunque. HolyArrs avvisa a ogni avvio. Questo non toglie mai il rifiuto per le condivisioni di rete.

Filesystem root in sola lettura

Devono essere scrivibili solo /config e /tmp:

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

PUID, PGID e UMASK funzionano comunque.

Avvio con un utente fisso

services:
  holyarrs:
    user: "1000:1000"

In questo caso HolyArrs non cambia nessun proprietario, quindi la cartella di configurazione deve essere già scrivibile da quell’utente. PUID e PGID vengono ignorati e il log lo dice. Vale anche per runAsUser di Kubernetes.

Docker rootless e Podman

In modalità rootless, root dentro il container è il tuo utente, e gli altri id vengono mappati su numeri alti sull’host. Con PUID=1000, la cartella di configurazione finisce con un proprietario sconosciuto sull’host.

Cosa usi	docker info o podman info mostra	Usa
Docker normale	niente rootless	PUID e PGID come al solito
Docker rootless	rootless sotto Security Options	Opzione 1
Podman rootless	rootless: true	Opzione 1 o 2

Opzione 1. Imposta PUID=0 e PGID=0. È sicuro solo in modalità rootless. Non farlo mai con Docker normale o su un NAS.

Opzione 2. Podman con keep-id, come Quadlet in ~/.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

Oppure come un unico comando:

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 serve per i sistemi con SELinux. Usa :z sulle cartelle condivise con il downloader. Non usare nessuno dei due su una condivisione di rete (NFS o SMB): non può essere rietichettata e il container non partirebbe.
• Indica il controllo di salute come elenco. L’immagine non ha una shell.
• Tieni il criterio di riavvio su always. Il servizio di Podman che avvia dopo il riavvio avvia solo i container always.
• Per avviare dopo un riavvio senza accedere, esegui una volta loginctl enable-linger $USER. Poi usa il file Quadlet, oppure per podman run esegui systemctl --user enable podman-restart.service.

Se la cartella appartiene già a un id alto, ferma prima il container, poi:

• Podman rootless: podman unshare chown -R 0:0 ~/holyarrs/config (Opzione 1) oppure podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Docker rootless: rootlesskit chown -R 0:0 ~/holyarrs/config, eseguito tramite nsenter nel daemon rootless (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Crea la tua immagine

Dal checkout di HolyArrs:

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

Poi usa holyarrs:local come immagine.

Risoluzione dei problemi

Esegui prima il doctor. Controlla configurazione, cartelle, rete e orologio, e ti dice come risolvere ogni problema.

• Container in esecuzione: docker exec holyarrs /holyarrs doctor
• Il container continua a riavviarsi: docker compose run --rm holyarrs doctor

Per il log e il pacchetto di supporto vedi Risoluzione dei problemi.

Cosa vedi	Cosa fare
Config folder is on a shared or network folder	Usa un disco locale, o un volume con nome su Docker Desktop. Su Unraid usa /mnt/<pool>/appdata/holyarrs.
Config folder is in memory	Metti /config su un disco. Su Unraid, controlla che il percorso del pool esista. Per un computer di prova, HOLYARRS_CONFIG_IN_MEMORY=yes lo permette.
Config folder cannot be written	Togli :ro e controlla che PUID:PGID siano proprietari della cartella.
Disk is full	Libera spazio sul disco che contiene /config, poi riavvia.
/config is not mapped	Vedi sotto.
Cannot switch user	Rimetti le quattro capability, oppure usa user: "<uid>:<gid>".
PUID/PGID does not exist inside this container	Gli id sono fuori dall’intervallo mappato. Vedi Docker rootless e Podman.
A FILE__ variable cannot be read	Controlla il percorso e che il file sia montato.
Permission denied	Controlla PUID, PGID e il permesso di scrittura su tutte le cartelle.
Unknown host name	Apri HolyArrs tramite IP e aggiungi il nome sotto Allowed host names.
Imports are copied	Monta una sola cartella condivisa. Vedi Cartelle multimediali.
Master key does not match	Rimetti la chiave che appartiene a quei database.
Restore staged but the app stays down	Aggiungi un criterio di riavvio e avvia il container.

Hai dimenticato di mappare /config?

HolyArrs parte comunque, ma avvisa ovunque. Tutto va perso quando il container viene rimosso. Salva prima i dati:

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

Poi mappa ./holyarrs-config:/config (o un volume con nome) e ricrea il container. Su Docker Desktop (Windows e Mac) usa un volume con nome, non una cartella dell’host, e copia dentro i dati come mostrato in Docker Desktop. Una configurazione più vecchia può ancora trovarsi in un volume senza nome. Elencali con docker volume ls.

Correlati

• Cartelle
• Primo avvio
• NAS, Synology e Unraid
• Aggiornamenti