Installeren

Draai HolyArrs in Docker en open het in je browser. Dat duurt een paar minuten.

Voor je begint

• Een computer met Docker en Docker Compose.
• Je mediamappen, of een plek om ze aan te maken. Lees eerst Mappen als je liever direct verplaatst dan kopieert.
• Op een NAS, Unraid of Synology: zie NAS, Synology en Unraid. Zonder Docker: zie Portable archieven.

Stappen

1. Maak een map voor de configuratie op een lokale schijf, bijvoorbeeld /srv/holyarrs/config. Geen netwerkshare. Gebruik op Docker Desktop in plaats daarvan een benoemd volume. Zie Docker Desktop.

2. Zoek de gebruiker en groep die eigenaar zijn van je mediamappen:

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

   Gebruik de uid als PUID en de gid als PGID.

3. Sla dit op als docker-compose.yml en pas de paden aan:

   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. Start het:

   docker compose up -d
   docker compose ps

   De container staat op healthy zodra HolyArrs antwoordt.

5. Open http://your-server:6262 en maak meteen het eigenaarsaccount aan. Er is geen standaardwachtwoord. Zolang je het account niet hebt aangemaakt, wordt de eerste die HolyArrs opent de eigenaar.

6. Volg de configuratie die daarna opent. Zie Eerste start.

Opgepast

Er is geen standaardwachtwoord. Wie een nieuwe HolyArrs als eerste opent, wordt de eigenaar. Maak het account nu aan.

Liever 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	Wat je krijgt
latest	De nieuwste versie
1.0.2 (elke versie)	Precies die versie, verandert nooit

Instellingen uitgelegd

Poorten en mappen

Instelling	Wat het doet
-p 6262:6262	De web-app.
-v /config	Databases, instellingen, de hoofdsleutel, backups en logs. Alleen lokale schijf.
-v /movies	Optioneel. Een bibliotheekmap voor films.
-v /tv	Optioneel. Een bibliotheekmap voor series.
-v /music	Optioneel. Een bibliotheekmap voor muziek.
-v /downloads	Optioneel. De downloadmap van de downloader. Zie Mediamappen.
--read-only=true	Optioneel. Zie Alleen-lezen rootbestandssysteem.
--user=1000:1000	Optioneel. Zie Starten als vaste gebruiker.

Omgevingsvariabelen

Variabele	Wat het doet
PUID, PGID	De gebruiker en groep waaronder HolyArrs draait. 1000 en 1000 als je ze weglaat.
TZ	Tijdzone, bijvoorbeeld Europe/Amsterdam.
UMASK	Optioneel. Welke rechtenbits nieuwe bestanden niet krijgen, bijvoorbeeld 022 of 002.
HOLYARRS_SAVE_PATH	Optioneel. De opslagmap van de downloader, zoals de downloader hem ziet.
HOLYARRS_ALLOWED_HOSTS	Optioneel. Extra hostnamen waarmee mensen HolyArrs bereiken, gescheiden door komma’s.
HOLYARRS_TRUSTED_PROXIES	Optioneel. Het adres of netwerk van je reverse proxy.
HOLYARRS_URL_BASE	Optioneel. Zet HolyArrs onder een pad. Zie Reverse proxy en URL base.
HOLYARRS_MASTER_KEY_FILE	Optioneel. Lees de hoofdsleutel uit een eigen bestand.

Elke variabele kan uit een bestand komen. Zet FILE__ voor de naam en geef het pad van het bestand als waarde:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Eén nieuwe regel aan het einde van het bestand wordt weggelaten. Dit werkt ook voor PUID, PGID, UMASK en TZ. Ontbreekt het bestand, dan stopt HolyArrs en staat de naam van de variabele in de log. De waarde zelf toont het nooit.

De image

De image bevat HolyArrs en bijna niets anders. Er is geen shell, dus je kunt er niet met docker exec in rondkijken. Lees in plaats daarvan de log met docker logs holyarrs, of open logs/holyarrs.log in de configuratiemap.

De eigen commando’s van HolyArrs werken nog wel via docker exec:

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

Er zijn images voor amd64, 64-bit ARM en 32-bit ARM. Op een computer met ongeveer 2,5 GiB geheugen of minder zet HolyArrs vanzelf de modus voor weinig geheugen aan. De eerste regel van de log meldt dat.

Gebruiker en groep

De container start alleen als root om zichzelf in te richten. Hij geeft de configuratiemap indien nodig aan PUID:PGID en schakelt dan voorgoed over naar die gebruiker. De eerste regel van de log toont de gebruiker, groep en umask.

HolyArrs wijzigt nooit de eigenaar van je media- of downloadmappen. Geef de PUID-gebruiker zelf schrijftoegang daartoe. Leestoegang is niet genoeg, want HolyArrs maakt mappen aan en verplaatst bestanden.

Sommige opslag kan geen eigenaars wijzigen, zoals NFS met root squash, SMB of een alleen-lezen mount. HolyArrs logt dan een waarschuwing en gaat door. Maak de configuratiemap dan zelf beschrijfbaar voor PUID:PGID.

Overschakelen naar een andere gebruiker vraagt de rechten CHOWN, DAC_OVERRIDE, SETUID en SETGID. Docker geeft ze standaard. Haal je ze weg, dan stopt HolyArrs met een melding. Het valt niet terug op root. Wil je echt als root draaien, zet dan PUID=0 en PGID=0.

Extra groepen uit group_add: blijven behouden als HolyArrs van gebruiker wisselt.

UMASK werkt alleen op nieuwe bestanden. Laat hem weg om 022 te houden: jij schrijft, anderen lezen. Gebruik 002 als ook een groep moet kunnen schrijven.

Mediamappen

Mount alleen de mappen die je gebruikt: /movies, /tv en /music als bibliotheekmappen en /downloads als downloadmap.

Tip voor hardlinks (harde koppelingen): elke map die je apart mount, is binnen de container een aparte mount, en een bestand kan niet over mounts heen worden gehardlinkt, dus imports worden volledige kopieën. Wil je hardlinks, mount dan in plaats van de vier optionele mounts één gedeelde bovenliggende map (met de downloads en bibliotheekmappen erin), en geef de downloader dezelfde mount op hetzelfde pad. De bovenliggende map moet ook één bestandssysteem zijn. Aparte NAS-shares of datasets eronder worden nog steeds gekopieerd. Settings > Library folders (Instellingen > Bibliotheekmappen) waarschuwt je wanneer HolyArrs moet kopiëren.

HOLYARRS_SAVE_PATH gaat bij elke download mee naar de downloader, dus het bepaalt ook waar de downloader opslaat. Laat het weg om de eigen instelling van de downloader te houden. Laat je het weg, voeg dan de downloadmap toe onder Settings > Library folders > Extra import folders (extra importmappen), zodat je er met de hand uit kunt importeren.

Bewaar de hoofdsleutel

HolyArrs versleutelt opgeslagen wachtwoorden, sleutels en tokens met een hoofdsleutel. De eerste start maakt /config/holyarrs.key aan.

Backups bevatten deze sleutel nooit. Bewaar een kopie ergens anders. De makkelijke manier: open als eigenaar Settings > Backups en kies Download key kit (sleutelpakket downloaden). Om hem terug te zetten, geef je het bestand de naam holyarrs.key en plaats je het in de configuratiemap terwijl HolyArrs gestopt is. Terugzetten met een andere sleutel wordt geweigerd. Bij een benoemd volume is er geen map om te openen: kopieer hem erin met docker cp holyarrs.key hx:/config/ zoals bij Docker Desktop. Verhuis je naar een nieuwe computer? Zet eerst de sleutel terug en daarna de backup. Zie Backups.

Je kunt de sleutel ook in een eigen alleen-lezen bestand bewaren:

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

Het bestand moet bestaan en 32 ruwe bytes, 64 hexadecimale cijfers of base64 voor 32 bytes bevatten. De PUID-gebruiker moet het kunnen lezen.

Herstart en terugzetten

Houd een herstartbeleid aan. Een backup terugzetten wordt eerst gecontroleerd en klaargezet, daarna sluit HolyArrs af met status 75 zodat Docker het opnieuw start en de backup toepast. unless-stopped regelt dat.

Om een lokale build te updaten, bouw je opnieuw en maak je de container opnieuw aan zonder de mounts aan te raken:

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

Verwijder /config nooit tijdens een update. Zie Updates en Backups.

Hostnamen en reverse proxies

IP-adressen en localhost werken zonder meer. Een thuisnaam zoals tower.local die je tijdens de eerste configuratie gebruikt, wordt voor je opgeslagen. Voeg andere namen toe onder Allowed host names (toegestane hostnamen) in Settings > Sign-in and security (Instellingen > Aanmelding en beveiliging), of in HOLYARRS_ALLOWED_HOSTS.

Voegt een reverse proxy X-Forwarded-For toe, zet dan alleen het adres of netwerk van de proxy in HOLYARRS_TRUSTED_PROXIES. Zonder dat werken single sign-on, echte clientadressen en de Secure-cookie niet, en iedereen achter de proxy deelt één aanmeldlimiet. De log noemt het proxyadres dat je moet toevoegen. Staat er nog een andere proxy voor, zoals Cloudflare, voeg dan ook de adresbereiken daarvan toe.

Stuur bij nginx beide headers mee:

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

Spreken de twee elkaar tegen, dan behandelt HolyArrs de bezoeker als iemand buiten je netwerk.

Basisbeveiliging

• Stuur poort 6262 niet door op je router. Gebruik een VPN zoals Tailscale, of een reverse proxy met HTTPS.
• Maak het eigenaarsaccount meteen na de eerste start aan.
• Bewaar een kopie van de hoofdsleutel buiten de configuratiemap.
• Houd de image up-to-date.

Speciale opstellingen

Docker Desktop (Windows en Mac)

Docker Desktop deelt hostmappen via een laag waarin bestandsvergrendeling voor databases niet veilig is. HolyArrs weigert daar een /config en toont de oplossing op poort 6262. Gebruik een benoemd volume voor /config. Mediamappen mogen hostmappen blijven.

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:

Om een oude configuratiemap naar het volume te verplaatsen, stop je HolyArrs en voer je uit:

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

Backups naar buiten kopiëren: docker cp holyarrs:/config/backups .

Heb je op een Mac gecontroleerd dat bestandsvergrendeling in je map werkt, stel dan HOLYARRS_ALLOW_DESKTOP_FOLDER=1 in om toch te starten. HolyArrs waarschuwt bij elke start. Dit heft de weigering voor netwerkshares nooit op.

Alleen-lezen rootbestandssysteem

Alleen /config en /tmp moeten beschrijfbaar zijn:

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

PUID, PGID en UMASK werken nog steeds.

Starten als vaste gebruiker

services:
  holyarrs:
    user: "1000:1000"

HolyArrs wijzigt dan geen eigenaars, dus de configuratiemap moet al beschrijfbaar zijn voor die gebruiker. PUID en PGID worden genegeerd en de log zegt dat. Dit geldt ook voor Kubernetes runAsUser.

Rootless Docker en Podman

In rootless-modus is root binnen de container je eigen gebruiker, en andere id’s worden op de host omgezet naar hoge nummers. Met PUID=1000 komt de configuratiemap in handen van een vreemde op de host.

Je draait	docker info of podman info toont	Gebruik
Gewone Docker	geen rootless	PUID en PGID zoals gewoonlijk
Rootless Docker	rootless onder Security Options	Optie 1
Rootless Podman	rootless: true	Optie 1 of 2

Optie 1. Zet PUID=0 en PGID=0. Dit is alleen veilig in rootless-modus. Doe dit nooit met gewone Docker of op een NAS.

Optie 2. Podman met keep-id, als 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

Of als één commando:

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 is voor SELinux-systemen. Gebruik :z op mappen die je met de downloader deelt. Gebruik geen van beide op een netwerkshare (NFS of SMB): die kan niet opnieuw gelabeld worden en de container zou niet starten.
• Geef de gezondheidscontrole als lijst op. De image heeft geen shell.
• Houd het herstartbeleid op always. De service van Podman die na een herstart weer opstart start alleen always-containers.
• Om na een herstart te starten zonder aan te melden, voer je eenmalig loginctl enable-linger $USER uit. Gebruik daarna het Quadlet-bestand, of voer bij podman run systemctl --user enable podman-restart.service uit.

Hoort de map al bij een hoog id, stop dan eerst de container en voer dan uit:

• Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (Optie 1) of podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, uitgevoerd via nsenter in de rootless daemon (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Bouw je eigen image

Vanuit je HolyArrs-checkout:

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

Gebruik daarna holyarrs:local als image.

Problemen oplossen

Voer eerst de doctor uit. Hij controleert de configuratie, mappen, netwerk en klok, en vertelt je hoe je elk probleem oplost.

• Container draait: docker exec holyarrs /holyarrs doctor
• Container blijft herstarten: docker compose run --rm holyarrs doctor

Zie Problemen oplossen voor de log en het ondersteuningspakket.

Je ziet	Doe dit
Config folder is on a shared or network folder	Gebruik een lokale schijf, of een benoemd volume op Docker Desktop. Gebruik op Unraid /mnt/<pool>/appdata/holyarrs.
Config folder is in memory	Zet /config op een schijf. Controleer op Unraid of het poolpad bestaat. Voor een testcomputer staat HOLYARRS_CONFIG_IN_MEMORY=yes het toe.
Config folder cannot be written	Haal :ro weg en controleer of PUID:PGID eigenaar van de map zijn.
Disk is full	Maak ruimte vrij op de schijf met /config en herstart dan.
/config is not mapped	Zie hieronder.
Cannot switch user	Voeg de vier rechten weer toe, of gebruik user: "<uid>:<gid>".
PUID/PGID does not exist inside this container	De id’s liggen buiten het toegewezen bereik. Zie Rootless Docker en Podman.
A FILE__ variable cannot be read	Controleer het pad en of het bestand gemount is.
Permission denied	Controleer PUID, PGID en schrijftoegang op alle mappen.
Unknown host name	Open HolyArrs via het IP-adres en voeg de naam toe onder Allowed host names.
Imports are copied	Mount één gedeelde map. Zie Mediamappen.
Master key does not match	Zet de sleutel terug die bij die databases hoort.
Restore staged but the app stays down	Voeg een herstartbeleid toe en start de container.

/config vergeten toe te wijzen?

HolyArrs start nog wel, maar waarschuwt overal. Alles is weg als de container wordt verwijderd. Bewaar het eerst:

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

Wijs daarna ./holyarrs-config:/config (of een benoemd volume) toe en maak de container opnieuw aan. Gebruik op Docker Desktop (Windows en Mac) een benoemd volume, geen hostmap, en kopieer de gegevens erin zoals bij Docker Desktop. Een oudere opstelling kan nog in een naamloos volume staan. Een lijst krijg je met docker volume ls.

Gerelateerde pagina’s

• Mappen
• Eerste start
• NAS, Synology en Unraid
• Updates