Installieren

Starte HolyArrs in Docker und öffne es in deinem Browser. Das dauert ein paar Minuten.

Bevor du beginnst

• Ein Rechner mit Docker und Docker Compose.
• Deine Medienordner oder ein Ort, an dem du sie anlegen kannst. Lies zuerst Ordner, wenn deine Dateien sofort verschoben statt kopiert werden sollen.
• Für ein NAS, Unraid oder Synology siehe NAS, Synology und Unraid. Ohne Docker siehe Portable Archive.

Schritte

1. Lege auf einem lokalen Datenträger einen Ordner für die Konfiguration an, zum Beispiel /srv/holyarrs/config. Keine Netzwerkfreigabe. Nimm unter Docker Desktop stattdessen ein benanntes Volume. Siehe Docker Desktop.

2. Finde heraus, welchem Benutzer und welcher Gruppe deine Medienordner gehören:

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

   Nimm die uid als PUID und die gid als PGID.

3. Speichere das hier als docker-compose.yml und ändere die Pfade:

   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. Starte es:

   docker compose up -d
   docker compose ps

   Der Container steht auf healthy, sobald HolyArrs antwortet.

5. Öffne http://your-server:6262 und lege sofort das Besitzerkonto an. Es gibt kein Standardpasswort. Solange das Konto fehlt, wird Besitzer, wer HolyArrs zuerst öffnet.

6. Folge der Einrichtung, die sich danach öffnet. Siehe Erster Start.

Achtung

Es gibt kein Standardpasswort. Wer ein neues HolyArrs zuerst öffnet, wird Besitzer. Lege das Konto jetzt an.

Wenn dir docker run lieber ist:

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	Was du bekommst
latest	Die neueste Version
1.0.2 (jede Version)	Genau diese Version, ändert sich nie

Die Einstellungen erklärt

Ports und Ordner

Einstellung	Was sie bewirkt
-p 6262:6262	Die Web-App.
-v /config	Datenbanken, Einstellungen, der Hauptschlüssel, Backups und Logs. Nur lokaler Datenträger.
-v /movies	Optional. Ein Bibliotheksordner für Filme.
-v /tv	Optional. Ein Bibliotheksordner für Serien.
-v /music	Optional. Ein Bibliotheksordner für Musik.
-v /downloads	Optional. Der Download-Ordner des Downloaders. Siehe Medienordner.
--read-only=true	Optional. Siehe Schreibgeschütztes Root-Dateisystem.
--user=1000:1000	Optional. Siehe Als fester Benutzer starten.

Umgebungsvariablen

Variable	Was sie bewirkt
PUID, PGID	Benutzer und Gruppe, unter denen HolyArrs läuft. 1000 und 1000, wenn du sie weglässt.
TZ	Zeitzone, zum Beispiel Europe/Amsterdam.
UMASK	Optional. Welche Berechtigungsbits neue Dateien nicht bekommen, zum Beispiel 022 oder 002.
HOLYARRS_SAVE_PATH	Optional. Der Speicherordner des Downloaders, so wie der Downloader ihn sieht.
HOLYARRS_ALLOWED_HOSTS	Optional. Weitere Hostnamen, über die HolyArrs aufgerufen wird, durch Kommas getrennt.
HOLYARRS_TRUSTED_PROXIES	Optional. Die Adresse oder das Netzwerk deines Reverse Proxy.
HOLYARRS_URL_BASE	Optional. HolyArrs unter einem Pfad ausliefern. Siehe URL base und Reverse Proxys.
HOLYARRS_MASTER_KEY_FILE	Optional. Den Hauptschlüssel aus einer eigenen Datei lesen.

Jede Variable kann aus einer Datei kommen. Setze FILE__ vor den Namen und gib den Pfad der Datei als Wert an:

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Ein Zeilenumbruch am Ende der Datei wird entfernt. Das geht auch für PUID, PGID, UMASK und TZ. Fehlt die Datei, stoppt HolyArrs und nennt die Variable im Log. Den Wert gibt es nie aus.

Das Image

Das Image enthält HolyArrs und kaum etwas anderes. Es hat keine Shell, du kannst dich also nicht mit docker exec darin umsehen. Lies stattdessen das Log mit docker logs holyarrs oder öffne logs/holyarrs.log im Konfigurationsordner.

Die eigenen Befehle von HolyArrs laufen trotzdem über docker exec:

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

Images gibt es für amd64, 64-Bit-ARM und 32-Bit-ARM. Auf einem Rechner mit etwa 2,5 GiB Arbeitsspeicher oder weniger schaltet HolyArrs den Modus für wenig Arbeitsspeicher von selbst ein. Die erste Zeile im Log sagt das.

Benutzer und Gruppe

Der Container startet als root, nur um sich einzurichten. Wenn nötig, übergibt er den Konfigurationsordner an PUID:PGID und wechselt dann dauerhaft zu diesem Benutzer. Die erste Zeile im Log zeigt Benutzer, Gruppe und umask.

HolyArrs ändert nie den Eigentümer deiner Medien- oder Download-Ordner. Gib dem PUID-Benutzer dort selbst Schreibzugriff. Lesezugriff reicht nicht, denn HolyArrs legt Ordner an und verschiebt Dateien.

Manche Speicher können den Eigentümer nicht ändern, etwa NFS mit root squash, SMB oder ein schreibgeschützter Mount. HolyArrs schreibt dann eine Warnung ins Log und macht weiter. Mache den Konfigurationsordner von Hand für PUID:PGID beschreibbar.

Der Benutzerwechsel braucht die Capabilities CHOWN, DAC_OVERRIDE, SETUID und SETGID. Docker vergibt sie standardmäßig. Wenn du sie entziehst, stoppt HolyArrs mit einer Meldung. Es weicht nicht auf root aus. Um wirklich als root zu laufen, setze PUID=0 und PGID=0.

Zusätzliche Gruppen aus group_add: bleiben erhalten, wenn HolyArrs den Benutzer wechselt.

UMASK wirkt nur auf neue Dateien. Lass es weg, um bei 022 zu bleiben: du schreibst, andere lesen. Nimm 002, wenn auch eine Gruppe schreiben muss.

Medienordner

Binde nur die Ordner ein, die du nutzt: /movies, /tv und /music als Bibliotheksordner und /downloads als Download-Ordner.

Tipp für Hardlinks (harte Verknüpfungen): Jeder Ordner, den du einzeln einbindest, ist im Container ein eigener Mount. Über Mounts hinweg lässt sich kein Hardlink auf eine Datei setzen, also werden Importe zu vollen Kopien. Wenn du Hardlinks willst, kannst du stattdessen einen gemeinsamen übergeordneten Ordner einbinden (mit den Downloads und den Bibliotheksordnern darin), anstelle der vier optionalen Mounts, und dem Downloader denselben Mount unter demselben Pfad geben. Der übergeordnete Ordner muss außerdem ein einziges Dateisystem sein. Getrennte NAS-Freigaben oder Datasets darunter werden weiterhin kopiert. Settings > Library folders (Einstellungen > Bibliotheksordner) warnt dich, wenn HolyArrs kopieren muss.

HOLYARRS_SAVE_PATH geht mit jedem Download an den Downloader und ändert damit auch, wohin der Downloader speichert. Lass es weg, um die eigene Einstellung des Downloaders zu behalten. Wenn du es weglässt, trage den Download-Ordner unter Settings > Library folders > Extra import folders (zusätzliche Importordner) ein, damit du von Hand daraus importieren kannst.

Den Hauptschlüssel aufbewahren

HolyArrs verschlüsselt gespeicherte Passwörter, Schlüssel und Tokens mit einem Hauptschlüssel. Der erste Start legt /config/holyarrs.key an.

Backups enthalten diesen Schlüssel nie. Bewahre eine Kopie an einem anderen Ort auf. Der einfache Weg: Öffne als Besitzer Settings > Backups (Einstellungen > Backups) und wähle Download key kit (Schlüsselpaket herunterladen). Um ihn zurückzulegen, nenne die Datei holyarrs.key und lege sie in den Konfigurationsordner, während HolyArrs gestoppt ist. Eine Wiederherstellung mit einem anderen Schlüssel wird abgelehnt. Bei einem benannten Volume gibt es keinen Ordner zum Öffnen: Kopiere ihn mit docker cp holyarrs.key hx:/config/ hinein, wie unter Docker Desktop. Du ziehst auf einen neuen Rechner um? Lege zuerst den Schlüssel zurück und stelle dann das Backup wieder her. Siehe Backups.

Du kannst den Schlüssel auch in einer eigenen schreibgeschützten Datei halten:

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

Die Datei muss vorhanden sein und 32 rohe Bytes, 64 Hex-Ziffern oder Base64 für 32 Bytes enthalten. Der PUID-Benutzer muss sie lesen können.

Neustart und Wiederherstellung

Behalte eine Neustart-Richtlinie. Eine Wiederherstellung wird geprüft und vorbereitet, dann beendet sich HolyArrs mit Status 75, damit Docker es neu startet und sie anwendet. unless-stopped erledigt das.

Um einen lokalen Build zu aktualisieren, baue neu und erstelle den Container neu, ohne die Mounts anzufassen:

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

Entferne /config nie während eines Updates. Siehe Updates und Backups.

Hostnamen und Reverse Proxys

IP-Adressen und localhost funktionieren ohne weiteres Zutun. Ein Name im Heimnetz wie tower.local, den du bei der ersten Einrichtung nutzt, wird für dich gespeichert. Weitere Namen trägst du unter Allowed host names (erlaubte Hostnamen) in Settings > Sign-in and security (Einstellungen > Anmeldung und Sicherheit) ein oder in HOLYARRS_ALLOWED_HOSTS.

Wenn ein Reverse Proxy X-Forwarded-For hinzufügt, trage nur die Adresse oder das Netzwerk des Proxys in HOLYARRS_TRUSTED_PROXIES ein. Ohne das funktionieren Single Sign-on, echte Client-Adressen und das Secure-Cookie nicht, und alle hinter dem Proxy teilen sich ein Anmeldelimit. Das Log nennt die Proxy-Adresse, die du eintragen musst. Sitzt noch ein Proxy davor, etwa Cloudflare, trage auch dessen Bereiche ein.

Mit nginx sendest du beide Header:

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

Wenn die beiden nicht übereinstimmen, behandelt HolyArrs den Besucher als außerhalb deines Netzwerks.

Grundlagen der Sicherheit

• Leite Port 6262 nicht an deinem Router weiter. Nimm ein VPN wie Tailscale oder einen Reverse Proxy mit HTTPS.
• Lege das Besitzerkonto gleich nach dem ersten Start an.
• Bewahre eine Kopie des Hauptschlüssels getrennt vom Konfigurationsordner auf.
• Halte das Image aktuell.

Besondere Setups

Docker Desktop (Windows und Mac)

Docker Desktop gibt Host-Ordner über eine Schicht frei, in der Dateisperren von Datenbanken nicht sicher sind. HolyArrs lehnt ein /config dort ab und zeigt die Lösung auf Port 6262. Nimm ein benanntes Volume für /config. Medienordner können Host-Ordner bleiben.

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:

Um einen alten Konfigurationsordner in das Volume zu verschieben, stoppe HolyArrs und führe aus:

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

Um Backups herauszukopieren: docker cp holyarrs:/config/backups .

Wenn du auf einem Mac geprüft hast, dass Dateisperren in deinem Ordner funktionieren, setze HOLYARRS_ALLOW_DESKTOP_FOLDER=1, um trotzdem zu starten. HolyArrs warnt bei jedem Start. Für Netzwerkfreigaben hebt das die Ablehnung nie auf.

Schreibgeschütztes Root-Dateisystem

Nur /config und /tmp müssen beschreibbar sein:

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

PUID, PGID und UMASK funktionieren weiterhin.

Als fester Benutzer starten

services:
  holyarrs:
    user: "1000:1000"

HolyArrs ändert dann keine Eigentümer, der Konfigurationsordner muss also schon für diesen Benutzer beschreibbar sein. PUID und PGID werden ignoriert, und das Log sagt das. Das gilt auch für runAsUser in Kubernetes.

Rootless Docker und Podman

Im Rootless-Modus ist root im Container dein eigener Benutzer, und andere IDs landen auf dem Host bei hohen Nummern. Mit PUID=1000 gehört der Konfigurationsordner auf dem Host am Ende einem Fremden.

Du nutzt	docker info oder podman info zeigt	Nimm
Normales Docker	kein rootless	PUID und PGID wie üblich
Rootless Docker	rootless unter Security Options	Option 1
Rootless Podman	rootless: true	Option 1 oder 2

Option 1. Setze PUID=0 und PGID=0. Das ist nur im Rootless-Modus sicher. Mache das nie mit normalem Docker oder auf einem NAS.

Option 2. Podman mit 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

Oder als ein Befehl:

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 ist für Systeme mit SELinux. Nimm :z bei Ordnern, die der Downloader mitnutzt. Nimm keins von beiden bei einer Netzwerkfreigabe (NFS oder SMB): Sie lässt sich nicht neu labeln, und der Container würde nicht starten.
• Gib die Zustandsprüfung als Liste an. Das Image hat keine Shell.
• Behalte die Neustart-Richtlinie always. Der Podman-Dienst für den Start nach einem Neustart startet nur Container mit always.
• Damit es nach einem Neustart ohne Anmeldung startet, führe einmal loginctl enable-linger $USER aus. Nimm dann die Quadlet-Datei, oder führe für podman run systemctl --user enable podman-restart.service aus.

Wenn der Ordner schon einer hohen ID gehört, stoppe zuerst den Container, dann:

• Rootless Podman: podman unshare chown -R 0:0 ~/holyarrs/config (Option 1) oder podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Rootless Docker: rootlesskit chown -R 0:0 ~/holyarrs/config, ausgeführt über nsenter im Rootless-Daemon (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Ein eigenes Image bauen

Aus dem HolyArrs-Checkout:

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

Nimm dann holyarrs:local als Image.

Fehlerbehebung

Führe zuerst den Doctor aus. Er prüft Konfiguration, Ordner, Netzwerk und Uhrzeit und sagt dir, wie du jedes Problem behebst.

• Container läuft: docker exec holyarrs /holyarrs doctor
• Container startet immer wieder neu: docker compose run --rm holyarrs doctor

Zum Log und zum Support-Paket siehe Fehlerbehebung.

Du siehst	Das hilft
Der Konfigurationsordner liegt auf einem freigegebenen Ordner oder einem Netzwerkordner	Nimm einen lokalen Datenträger oder unter Docker Desktop ein benanntes Volume. Unter Unraid nimm /mnt/<pool>/appdata/holyarrs.
Der Konfigurationsordner liegt im Arbeitsspeicher	Lege /config auf einen Datenträger. Prüfe unter Unraid, ob der Pool-Pfad existiert. Für einen Testrechner erlaubt HOLYARRS_CONFIG_IN_MEMORY=yes es.
Der Konfigurationsordner ist nicht beschreibbar	Entferne :ro und prüfe, ob der Ordner PUID:PGID gehört.
Der Datenträger ist voll	Schaffe freien Speicherplatz auf dem Datenträger, auf dem /config liegt, und starte dann neu.
/config ist nicht zugeordnet	Siehe unten.
Benutzerwechsel nicht möglich	Gib die vier Capabilities zurück oder nimm user: "<uid>:<gid>".
PUID/PGID existiert in diesem Container nicht	Die IDs liegen außerhalb des zugeordneten Bereichs. Siehe Rootless Docker und Podman.
Eine FILE__-Variable lässt sich nicht lesen	Prüfe den Pfad und ob die Datei eingebunden ist.
Zugriff verweigert	Prüfe PUID, PGID und den Schreibzugriff auf alle Ordner.
Unbekannter Hostname	Öffne HolyArrs über die IP und trage den Namen unter Allowed host names ein.
Importe werden kopiert	Binde einen gemeinsamen Ordner ein. Siehe Medienordner.
Der Hauptschlüssel passt nicht	Lege den Schlüssel zurück, der zu diesen Datenbanken gehört.
Wiederherstellung vorbereitet, aber die App bleibt aus	Füge eine Neustart-Richtlinie hinzu und starte den Container.

Vergessen, /config zuzuordnen?

HolyArrs startet trotzdem, warnt aber überall. Alles geht verloren, wenn der Container entfernt wird. Sichere es vorher:

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

Ordne dann ./holyarrs-config:/config (oder ein benanntes Volume) zu und erstelle den Container neu. Nimm unter Docker Desktop (Windows und Mac) ein benanntes Volume, keinen Host-Ordner, und kopiere die Daten hinein wie unter Docker Desktop gezeigt. Ein älteres Setup liegt vielleicht noch in einem unbenannten Volume. Liste sie mit docker volume ls auf.

Verwandte Seiten

• Ordner
• Erster Start
• NAS, Synology und Unraid
• Updates