Installer

Lancez HolyArrs dans Docker et ouvrez-le dans votre navigateur. Cela prend quelques minutes.

Avant de commencer

• Une machine avec Docker et Docker Compose.
• Vos dossiers multimédias, ou un endroit où les créer. Lisez d’abord Dossiers si vous voulez des déplacements instantanés plutôt que des copies.
• Sur un NAS, Unraid ou Synology, voir NAS, Synology et Unraid. Sans Docker, voir Archives portables.

Étapes

1. Créez un dossier pour la configuration sur un disque local, par exemple /srv/holyarrs/config. Pas sur un partage réseau. Sur Docker Desktop, utilisez plutôt un volume nommé. Voir Docker Desktop.

2. Trouvez l’utilisateur et le groupe propriétaires de vos dossiers multimédias :

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

   Utilisez l’uid comme PUID et le gid comme PGID.

3. Enregistrez ceci sous le nom docker-compose.yml et modifiez les chemins :

   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. Démarrez-le :

   docker compose up -d
   docker compose ps

   Le conteneur est indiqué comme sain dès que HolyArrs répond.

5. Ouvrez http://your-server:6262 et créez tout de suite le compte propriétaire. Il n’y a pas de mot de passe par défaut. Tant que ce compte n’existe pas, la première personne qui ouvre HolyArrs devient propriétaire.

6. Suivez la configuration qui s’ouvre ensuite. Voir Premier lancement.

Attention

Il n’y a pas de mot de passe par défaut. La première personne qui ouvre un nouveau HolyArrs devient propriétaire. Créez le compte maintenant.

Si vous préférez 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 de l’image

Tag	Ce que vous obtenez
latest	La version la plus récente
1.0.2 (n’importe quelle version)	Cette version précise, qui ne change jamais

Les paramètres expliqués

Ports et dossiers

Paramètre	Ce que ça fait
-p 6262:6262	L’interface web.
-v /config	Bases de données, paramètres, clé maîtresse, sauvegardes et journaux. Disque local uniquement.
-v /movies	Facultatif. Un dossier de bibliothèque pour les films.
-v /tv	Facultatif. Un dossier de bibliothèque pour les séries.
-v /music	Facultatif. Un dossier de bibliothèque pour la musique.
-v /downloads	Facultatif. Le dossier de téléchargement du client de téléchargement. Voir Dossiers multimédias.
--read-only=true	Facultatif. Voir Système de fichiers racine en lecture seule.
--user=1000:1000	Facultatif. Voir Démarrer avec un utilisateur fixe.

Variables d’environnement

Variable	Ce que ça fait
PUID, PGID	L’utilisateur et le groupe sous lesquels HolyArrs tourne. 1000 et 1000 si vous ne les indiquez pas.
TZ	Fuseau horaire, par exemple Europe/Amsterdam.
UMASK	Facultatif. Les bits de permission que les nouveaux fichiers n’ont pas, par exemple 022 ou 002.
HOLYARRS_SAVE_PATH	Facultatif. Le dossier d’enregistrement du client de téléchargement, tel que le client le voit.
HOLYARRS_ALLOWED_HOSTS	Facultatif. Les noms d’hôte supplémentaires utilisés pour joindre HolyArrs, séparés par des virgules.
HOLYARRS_TRUSTED_PROXIES	Facultatif. L’adresse ou le réseau de votre reverse proxy.
HOLYARRS_URL_BASE	Facultatif. Sert HolyArrs sous un chemin. Voir Reverse proxy et URL de base.
HOLYARRS_MASTER_KEY_FILE	Facultatif. Lit la clé maîtresse depuis son propre fichier.

Toute variable peut venir d’un fichier. Ajoutez FILE__ devant le nom et donnez le chemin du fichier comme valeur :

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

Un saut de ligne à la fin du fichier est ignoré. Cela fonctionne aussi pour PUID, PGID, UMASK et TZ. Si le fichier est absent, HolyArrs s’arrête et nomme la variable dans le journal. Il n’affiche jamais la valeur.

L’image

L’image contient HolyArrs et presque rien d’autre. Elle n’a pas de shell, donc vous ne pouvez pas y entrer avec docker exec pour regarder ce qu’il y a dedans. Lisez plutôt le journal avec docker logs holyarrs, ou ouvrez logs/holyarrs.log dans le dossier de configuration.

Les commandes de HolyArrs fonctionnent quand même avec docker exec :

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

Les images sont construites pour amd64, ARM 64 bits et ARM 32 bits. Sur une machine avec environ 2,5 Gio de mémoire ou moins, HolyArrs active tout seul le mode mémoire réduite. La première ligne du journal le signale.

Utilisateur et groupe

Le conteneur démarre en tant que root uniquement pour se préparer. Il donne le dossier de configuration à PUID:PGID si nécessaire, puis passe définitivement à cet utilisateur. La première ligne du journal indique l’utilisateur, le groupe et l’umask.

HolyArrs ne change jamais le propriétaire de vos dossiers multimédias ou de téléchargement. Donnez vous-même à l’utilisateur PUID l’accès en écriture à ces dossiers. L’accès en lecture ne suffit pas, car HolyArrs crée des dossiers et déplace des fichiers.

Certains stockages ne permettent pas de changer de propriétaire, par exemple NFS avec root squash, SMB ou un montage en lecture seule. HolyArrs écrit alors un avertissement dans le journal et continue. Rendez le dossier de configuration accessible en écriture pour PUID:PGID à la main.

Le changement d’utilisateur a besoin des capabilities CHOWN, DAC_OVERRIDE, SETUID et SETGID. Docker les donne par défaut. Si vous les retirez, HolyArrs s’arrête avec un message. Il ne se rabat pas sur root. Pour vraiment tourner en tant que root, mettez PUID=0 et PGID=0.

Les groupes supplémentaires de group_add: sont conservés quand HolyArrs change d’utilisateur.

UMASK ne joue que sur les nouveaux fichiers. Ne l’indiquez pas pour garder 022 : vous écrivez et les autres lisent. Utilisez 002 quand un groupe doit aussi écrire.

Dossiers multimédias

Montez seulement les dossiers que vous utilisez : /movies, /tv et /music comme dossiers de bibliothèque et /downloads comme dossier de téléchargement.

Astuce pour les hardlinks (liens physiques) : chaque dossier monté à part est un montage distinct dans le conteneur, et un hardlink ne peut pas relier deux montages, donc les imports deviennent des copies complètes. Si vous voulez des hardlinks, vous pouvez monter à la place un seul dossier parent partagé (avec les téléchargements et les dossiers de bibliothèque dedans) au lieu des quatre montages facultatifs, et donner au client de téléchargement le même montage au même chemin. Le dossier parent doit aussi être un seul système de fichiers. Des partages NAS ou des datasets séparés placés dessous entraînent quand même des copies. Settings > Library folders (Paramètres > Dossiers de bibliothèque) vous prévient quand HolyArrs doit copier.

HOLYARRS_SAVE_PATH est envoyé au client de téléchargement avec chaque téléchargement, donc il change aussi l’endroit où le client enregistre. Ne l’indiquez pas pour garder le paramètre du client. Dans ce cas, ajoutez le dossier de téléchargement dans Settings > Library folders > Extra import folders (dossiers d’import supplémentaires) pour pouvoir importer à la main depuis ce dossier.

Conserver la clé maîtresse

HolyArrs chiffre les mots de passe, clés et jetons stockés avec une clé maîtresse. Le premier démarrage crée /config/holyarrs.key.

Les sauvegardes ne contiennent jamais cette clé. Gardez-en une copie ailleurs. Le plus simple : en tant que propriétaire, ouvrez Settings > Backups (Paramètres > Sauvegardes) et choisissez Download key kit (télécharger le kit de clé). Pour la remettre en place, nommez le fichier holyarrs.key et placez-le dans le dossier de configuration pendant que HolyArrs est arrêté. Une restauration avec une autre clé est refusée. Avec un volume nommé, il n’y a pas de dossier à ouvrir : copiez-la dedans avec docker cp holyarrs.key hx:/config/ comme dans Docker Desktop. Vous changez de machine ? Remettez d’abord la clé, puis restaurez la sauvegarde. Voir Sauvegardes.

Vous pouvez aussi garder la clé dans son propre fichier en lecture seule :

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

Le fichier doit exister et contenir 32 octets bruts, 64 chiffres hexadécimaux ou 32 octets en base64. L’utilisateur PUID doit pouvoir le lire.

Redémarrage et restauration

Gardez une politique de redémarrage. Une restauration est vérifiée et préparée, puis HolyArrs se ferme avec le statut 75 pour que Docker le redémarre et l’applique. unless-stopped s’en charge.

Pour mettre à jour une image construite en local, reconstruisez et recréez sans toucher aux montages :

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

Ne supprimez jamais /config pendant une mise à jour. Voir Mises à jour et Sauvegardes.

Noms d’hôte et reverse proxies

Les adresses IP et localhost fonctionnent sans rien faire. Un nom domestique comme tower.local que vous utilisez pendant la première configuration est enregistré pour vous. Ajoutez d’autres noms sous Allowed host names (noms d’hôte autorisés) dans Settings > Sign-in and security (Paramètres > Connexion et sécurité), ou dans HOLYARRS_ALLOWED_HOSTS.

Quand un reverse proxy ajoute X-Forwarded-For, mettez seulement l’adresse ou le réseau du proxy dans HOLYARRS_TRUSTED_PROXIES. Sans cela, l’authentification unique (SSO), les vraies adresses des clients et le cookie Secure ne fonctionnent pas, et tous ceux qui passent par le proxy partagent une seule limite de connexion. Le journal nomme l’adresse du proxy à ajouter. Si un autre proxy se trouve devant, comme Cloudflare, ajoutez aussi ses plages.

Avec nginx, envoyez les deux en-têtes :

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

Si les deux ne concordent pas, HolyArrs traite le visiteur comme extérieur à votre réseau.

Les bases de la sécurité

• Ne redirigez pas le port 6262 sur votre routeur. Utilisez un VPN comme Tailscale, ou un reverse proxy avec HTTPS.
• Créez le compte propriétaire juste après le premier démarrage.
• Gardez une copie de la clé maîtresse ailleurs que dans le dossier de configuration.
• Tenez l’image à jour.

Installations particulières

Docker Desktop (Windows et Mac)

Docker Desktop partage les dossiers de l’hôte à travers une couche où les verrous de fichiers des bases de données ne sont pas fiables. HolyArrs refuse un /config placé là et affiche la solution sur le port 6262. Utilisez un volume nommé pour /config. Les dossiers multimédias peuvent rester des dossiers de l’hôte.

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:

Pour déplacer un ancien dossier de configuration dans le volume, arrêtez HolyArrs et lancez :

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

Pour sortir les sauvegardes : docker cp holyarrs:/config/backups .

Sur un Mac, si vous avez vérifié que les verrous de fichiers fonctionnent dans votre dossier, mettez HOLYARRS_ALLOW_DESKTOP_FOLDER=1 pour démarrer quand même. HolyArrs avertit à chaque démarrage. Cela ne lève jamais le refus pour les partages réseau.

Système de fichiers racine en lecture seule

Seuls /config et /tmp doivent être accessibles en écriture :

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

PUID, PGID et UMASK fonctionnent toujours.

Démarrer avec un utilisateur fixe

services:
  holyarrs:
    user: "1000:1000"

HolyArrs ne change alors aucun propriétaire, donc le dossier de configuration doit déjà être accessible en écriture pour cet utilisateur. PUID et PGID sont ignorés et le journal le signale. Cela couvre aussi runAsUser de Kubernetes.

Docker rootless et Podman

En mode rootless, root dans le conteneur est votre propre utilisateur, et les autres id correspondent à des numéros élevés sur l’hôte. Avec PUID=1000, le dossier de configuration finit par appartenir à un inconnu sur l’hôte.

Vous utilisez	docker info ou podman info affiche	Utilisez
Docker normal	pas de rootless	PUID et PGID comme d’habitude
Docker rootless	rootless sous Security Options	Option 1
Podman rootless	rootless: true	Option 1 ou 2

Option 1. Mettez PUID=0 et PGID=0. C’est sûr uniquement en mode rootless. Ne le faites jamais avec Docker normal ni sur un NAS.

Option 2. Podman avec keep-id, sous forme de Quadlet dans ~/.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

Ou en une seule commande :

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 sert aux systèmes SELinux. Utilisez :z sur les dossiers que le client de téléchargement partage. N’utilisez ni l’un ni l’autre sur un partage réseau (NFS ou SMB) : il ne peut pas être réétiqueté et le conteneur ne démarrerait pas.
• Donnez le contrôle de santé sous forme de liste. L’image n’a pas de shell.
• Gardez la politique de redémarrage always. Le service de Podman qui relance après un redémarrage de la machine ne démarre que les conteneurs always.
• Pour démarrer après un redémarrage de la machine sans vous connecter, lancez loginctl enable-linger $USER une fois. Utilisez ensuite le fichier Quadlet, ou, pour podman run, lancez systemctl --user enable podman-restart.service.

Si le dossier appartient déjà à un id élevé, arrêtez d’abord le conteneur, puis :

• Podman rootless : podman unshare chown -R 0:0 ~/holyarrs/config (Option 1) ou podman unshare chown -R 1000:1000 ~/holyarrs/config.
• Docker rootless : rootlesskit chown -R 0:0 ~/holyarrs/config, lancé avec nsenter dans le daemon rootless (nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)).

Construire votre propre image

Depuis votre copie du code de HolyArrs :

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

Utilisez ensuite holyarrs:local comme image.

Dépannage

Lancez d’abord le diagnostic. Il contrôle la configuration, les dossiers, le réseau et l’horloge, et vous dit comment corriger chaque problème.

• Le conteneur tourne : docker exec holyarrs /holyarrs doctor
• Le conteneur redémarre sans arrêt : docker compose run --rm holyarrs doctor

Voir Dépannage pour le journal et l’archive de diagnostic.

Vous voyez	Faites ceci
Le dossier de configuration est sur un dossier partagé ou réseau	Utilisez un disque local, ou un volume nommé sur Docker Desktop. Sur Unraid, utilisez /mnt/<pool>/appdata/holyarrs.
Le dossier de configuration est en mémoire	Placez /config sur un disque. Sur Unraid, vérifiez que le chemin du pool existe. Pour une machine de test, HOLYARRS_CONFIG_IN_MEMORY=yes l’autorise.
Impossible d’écrire dans le dossier de configuration	Supprimez :ro et vérifiez que PUID:PGID sont propriétaires du dossier.
Le disque est plein	Libérez de l’espace sur le disque qui contient /config, puis redémarrez.
/config n’est pas mappé	Voir ci-dessous.
Impossible de changer d’utilisateur	Remettez les quatre capabilities, ou utilisez user: "<uid>:<gid>".
PUID/PGID n’existe pas dans ce conteneur	Les id sont en dehors de la plage mappée. Voir Docker rootless et Podman.
Une variable FILE__ ne peut pas être lue	Vérifiez le chemin et que le fichier est bien monté.
Permission refusée	Vérifiez PUID, PGID et l’accès en écriture sur tous les dossiers.
Nom d’hôte inconnu	Ouvrez HolyArrs par son adresse IP et ajoutez le nom sous Allowed host names.
Les imports sont copiés	Montez un seul dossier partagé. Voir Dossiers multimédias.
La clé maîtresse ne correspond pas	Remettez la clé qui va avec ces bases de données.
Restauration préparée mais l’application reste arrêtée	Ajoutez une politique de redémarrage et démarrez le conteneur.

Vous avez oublié de mapper /config ?

HolyArrs démarre quand même, mais avertit partout. Tout est perdu quand le conteneur est supprimé. Mettez d’abord les données à l’abri :

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

Mappez ensuite ./holyarrs-config:/config (ou un volume nommé) et recréez le conteneur. Sur Docker Desktop (Windows et Mac), utilisez un volume nommé, pas un dossier de l’hôte, et copiez les données dedans comme indiqué dans Docker Desktop. Une installation plus ancienne se trouve peut-être encore dans un volume sans nom. Affichez-les avec docker volume ls.

Voir aussi

• Dossiers
• Premier lancement
• NAS, Synology et Unraid
• Mises à jour