🇬🇧 English · 🇫🇷 Français

S'applique à Hydranos 4.4.

Cette page s'adresse à vous si vous faites tourner Hydranos dans un conteneur : docker run simple, Docker Compose, Unraid, ou le gestionnaire de conteneurs d'un NAS comme celui de Synology. À la fin, vous aurez un conteneur qui conserve son état d'une mise à jour à l'autre, s'arrête proprement quand Docker l'arrête, écrit les fichiers sous votre utilisateur et est prêt pour l'écran de premier démarrage. Les termes employés ici (store, état de reprise, catégorie) sont définis dans Concepts & glossaire.

En bref : épinglez un tag de version, montez /config et un dossier de données, gardez stop_grace_period: 150s et restart: unless-stopped. Les boutons de redémarrage de l'interface web arrêtent Hydranos de la même façon propre que docker stop et comptent sur cette politique de redémarrage pour le relancer (voir Délai de grâce à l'arrêt plus bas).

Les images sont construites quand un tag de version est poussé, ou quand le mainteneur lance le build à la main. L'image contient un seul binaire, hydranos ; les versions ne livrent plus de hydranos-engine. Épinglez un tag de version (:v4.4.0) plutôt que :latest : c'est alors vous qui décidez quand une mise à jour a lieu, et vous pouvez faire une sauvegarde avant.

L'ancien nom d'image ghcr.io/kheopsian/hydra est déprécié : ne l'utilisez pas, tirez ghcr.io/kheopsian/hydranos.

L'image ne déclare aucun VOLUME ni HEALTHCHECK. Si vous oubliez de monter /config, tout ce que sait Hydranos vit dans la couche du conteneur et disparaît la prochaine fois que le conteneur est recréé.

flowchart LR
  subgraph HOST["Hôte Docker"]
    P1["8199/tcp"]
    P2["16171/tcp + 16171/udp"]
    P3["16172/tcp + 16172/udp"]
    D1["./config"]
    D2["./data"]
  end
  subgraph CT["conteneur"]
    EP["entrypoint.sh"] --> HY["processus hydranos"]
    C1["/config"]
    C2["/data"]
    HY --- R["moteur race<br/>écoute 16171"]
    HY --- HO["moteur hoard<br/>écoute 16172"]
  end
  P1 -->|"interface web, API REST, shim qBittorrent, MCP"| HY
  P2 --> R
  P3 --> HO
  D1 --- C1
  D2 --- C2
  C1 -->|"configuration, store, état de reprise, journal"| HY
  C2 -->|"données des torrents, via les chemins de sauvegarde des catégories"| HY

Voici le fichier compose de référence pour Hydranos 4.4. Il suit le docker-compose.yml fourni dans le dépôt ; les différences qui comptent sont un tag épinglé au lieu de :latest (voir Image plus haut) et PUID/PGID définis plutôt que commentés.

services:
  hydranos:
    image: ghcr.io/kheopsian/hydranos:v4.4.1
    container_name: hydranos
    # Les boutons de redémarrage de l'interface web sortent avec le code 75 et comptent sur ceci.
    restart: unless-stopped
    # Temps que Docker attend après SIGTERM avant d'envoyer SIGKILL.
    # Hydranos prévient les trackers qu'il s'en va (5 s au plus), puis écrit
    # l'état de reprise de chaque moteur dans HYDRANOS_STOP_TIMEOUT (120 s par
    # défaut). Gardez cette valeur au-dessus de ce budget. Voir plus bas.
    stop_grace_period: 150s
    # Un fichier ouvert par connexion de pair : l'entrypoint relève la limite
    # de fichiers ouverts à 1000000, ce qui ne marche que si la limite dure le permet.
    ulimits:
      nofile:
        soft: 1048576
        hard: 1048576
    # Mode réseau « WireGuard, managed by Hydranos » seulement (voir WireGuard géré) :
    # il demande NET_ADMIN ; le sysctl garde le côté IPv6 d'un .conf double pile.
    # Avec PUID/PGID, définissez aussi HYDRANOS_CAP_NET_ADMIN: "1" plus bas.
    # cap_add:
    #   - NET_ADMIN
    # sysctls:
    #   net.ipv6.conf.default.disable_ipv6: 0
    ports:
      - "8199:8199/tcp"      # interface web, API REST, shim qBittorrent, MCP
      - "16171:16171/tcp"    # moteur race, pairs (TCP)
      - "16171:16171/udp"    # moteur race, pairs (uTP)
      - "16172:16172/tcp"    # moteur hoard, pairs (TCP)
      - "16172:16172/udp"    # moteur hoard, pairs (uTP)
    environment:
      # Tourner sous votre utilisateur (voir « Utilisateur et permissions »). Retirez les deux lignes pour tourner en root.
      PUID: "1000"
      PGID: "1000"
      # Budget d'écriture à l'arrêt : 120, 90s, 2m ou 1m30s. Relevez stop_grace_period avec.
      # HYDRANOS_STOP_TIMEOUT: "120"
      # WireGuard géré avec PUID/PGID : garder NET_ADMIN après l'abandon de privilèges.
      # HYDRANOS_CAP_NET_ADMIN: "1"
    # Le pilote json-file de Docker garde tout, sauf indication contraire.
    logging:
      driver: json-file
      options:
        max-size: "128m"
        max-file: "5"
    volumes:
      - ./config:/config     # configuration, store, état de reprise, journal
      - ./data:/data         # vos données de torrents : UN SEUL dossier parent (voir Volumes)
      # Vous venez de qBittorrent ? Utilisez le chemin conteneur qu'avait qBittorrent
      # (p. ex. /downloads) au lieu de /data : voir Migrer depuis qBittorrent.

Démarrez-le :

mkdir -p config data      # créez-les vous-même, pour qu'ils appartiennent à votre utilisateur
docker compose up -d
docker compose logs -f hydranos

Créez les deux dossiers avant le premier up : un dossier de bind mount qui n'existe pas est créé par Docker, appartient à root, et un conteneur qui tourne avec PUID/PGID ne peut alors pas écrire dans /data.

Le même conteneur avec docker run :

docker run -d --name hydranos --restart unless-stopped \
  --stop-timeout 150 \
  --ulimit nofile=1048576:1048576 \
  --log-opt max-size=128m --log-opt max-file=5 \
  -p 8199:8199/tcp \
  -p 16171:16171/tcp -p 16171:16171/udp \
  -p 16172:16172/tcp -p 16172:16172/udp \
  -e PUID=1000 -e PGID=1000 \
  -v "$PWD/config:/config" -v "$PWD/data:/data" \
  ghcr.io/kheopsian/hydranos:v4.4.1

Pour le mode WireGuard géré, ajoutez --cap-add NET_ADMIN --sysctl net.ipv6.conf.default.disable_ipv6=0 (et -e HYDRANOS_CAP_NET_ADMIN=1 avec PUID/PGID) ; les prérequis sont sur WireGuard géré.

Publiez le port de chaque moteur en TCP et en UDP : uTP utilise l'UDP sur le même numéro. Gardez le port hôte égal au port du conteneur : un moteur annonce son propre port d'écoute aux trackers, donc 26171:16171 annoncerait un port que personne ne peut joindre. La liste complète des ports (moteurs supplémentaires compris) se trouve sur Installation & premier démarrage.

Si vous changez api_port dans default.toml, changez aussi le mappage. Le mode de secours (store impossible à ouvrir) répond sur les mêmes api_host/api_port que le mode normal.

Avec le réseau bridge par défaut, la redirection de port automatique (NAT-PMP/UPnP, active par défaut) a peu de chances d'atteindre votre routeur. Si le journal répète no automatic port forward; if you are not reachable, forward <port> (TCP and UDP) by hand, redirigez vous-même 16171 et 16172 (TCP et UDP) sur le routeur. Détails : Réseau : ports & redirection.

Sur SIGTERM, Hydranos s'arrête en trois étapes bornées, puis se termine :

1. Vidange de l'API, 5 s au plus. Le flux d'événements de l'interface web et le suivi en direct du journal se ferment d'eux-mêmes quand l'arrêt commence, donc un onglet ouvert ne retient plus la vidange ; ce qui est encore ouvert au bout de 5 s est abandonné (connections still open 5 s into the drain …; flushing without them).
2. Départs, 5 s au plus : chaque moteur prévient ses trackers qu'il s'en va (stopped).
3. Écriture de l'état de reprise, un thread par moteur en parallèle, bornée par HYDRANOS_STOP_TIMEOUT (120 s par défaut ; 120, 90s, 2m, 1m30s et 1h sont acceptés). Elle journalise shutdown flush complete (avec took_s), ou shutdown flush hit HYDRANOS_STOP_TIMEOUT; leaving with what is saved quand le budget s'épuise d'abord.

Par défaut, Docker envoie SIGKILL au bout de 10 s. Si le kill tombe pendant l'écriture, le démarrage suivant repart de la dernière sauvegarde périodique de l'état de reprise (toutes les 300 s) : la progression et les compteurs depuis ce moment sont perdus, et ce qui était en cours est revérifié. Le pire cas est 5 + 5 + 120 = 130 s, donc 150 s laisse de la marge. Si vous relevez HYDRANOS_STOP_TIMEOUT pour une grosse bibliothèque, relevez stop_grace_period avec (gardez-le au moins 10 s au-dessus) ; lisez la valeur took_s après un arrêt pour voir combien de temps l'écriture prend réellement. Plus de détails sur Exploiter Hydranos.

Compose recopie stop_grace_period dans le délai d'arrêt propre au conteneur, donc un simple docker stop hydranos l'utilise aussi. Un docker stop -t 10 tapé à la main le remplace.

Un redémarrage depuis l'interface web (par exemple Redémarrer maintenant (Restart now) après une modification de moteur) passe par les mêmes trois étapes, puis se termine avec le code 75 au lieu de 0 ; restart: unless-stopped relance le conteneur. Sans politique de redémarrage, le conteneur reste arrêté. Voir Exploiter Hydranos.

L'image n'en a pas. Vous pouvez en ajouter un ; /health ne demande pas de clé API. L'image n'a ni curl ni wget, la sonde utilise donc bash. Faites correspondre le mot d'état entier : un simple grep -q healthy correspond aussi à "unhealthy", et laisserait donc passer un démon qui répond 503.

    healthcheck:
      test:
        - CMD
        - bash
        - -c
        - exec 3<>/dev/tcp/127.0.0.1/8199 && printf 'GET /health HTTP/1.0\r\n\r\n' >&3 && grep -qE '"status":"(healthy|degraded|starting)"' <&3
      interval: 60s
      timeout: 10s
      retries: 3

Le port 8199 s'ouvre dans la première seconde, avant le chargement des torrents : pendant ce chargement, /health répond starting (HTTP 200), donc aucun long start_period n'est nécessaire. La sonde passe sur starting, healthy et degraded, et échoue sur unhealthy (HTTP 503 : le store ne répond pas, ou aucun moteur n'écoute les pairs), sur le mode de secours (ok tout court) et quand rien ne répond. Retirez degraded du motif pour signaler aussi un moteur sans écoute, bloqué par le kill switch ou retenu par start_paused. Les états sont expliqués sur Supervision & journaux. Docker marque le conteneur unhealthy ; il ne le redémarre pas.

Ce que sont le store et l'état de reprise, et en quoi ils diffèrent : Architecture.

Au premier démarrage, l'entrypoint copie la configuration par défaut de l'image vers /config/default.toml et y règle data_dir = "/config" : dans Docker, le dossier de configuration et le dossier de données (data_dir, pas le montage /data) sont donc le même dossier. C'est l'ensemble de /config que vous sauvegardez (conteneur arrêté d'abord) : Exploiter Hydranos.

Il n'y a pas de chemin de sauvegarde par défaut. Rien dans Hydranos n'écrit de lui-même dans /data : un torrent est refusé s'il n'a pas de chemin de sauvegarde ou une catégorie qui en a un. Créez des catégories dont les chemins de sauvegarde sont des chemins du conteneur situés dans un volume monté, par exemple /data/race et /data/library. Un chemin de sauvegarde hors de tout montage écrit dans la couche du conteneur et disparaît quand celui-ci est recréé. Voir Catégories & routage.

Si Sonarr, Radarr ou un autre outil lit les mêmes fichiers, montez le même dossier hôte au même chemin dans les deux conteneurs, pour que les chemins indiqués par Hydranos existent aussi de leur côté : Shim qBittorrent & automatisation. Si vous venez de qBittorrent, gardez le chemin conteneur qu'il utilisait : Migrer depuis qBittorrent.

Les hardlinks et les déplacements instantanés ne fonctionnent qu'à l'intérieur d'un seul montage. Linux refuse link() et rename() entre deux bind mounts avec EXDEV, même quand les deux sont sur le même disque. Cela touche les liens et déplacements de Duplicate data d'Hydranos, ainsi que les imports par hardlink de Sonarr/Radarr.

Montez donc un seul dossier parent qui contient à la fois les téléchargements et les médias, au même chemin dans chaque conteneur :

host:  /srv/data/torrents/...   /srv/data/media/...
mount: /srv/data:/data          in Hydranos AND in Sonarr/Radarr

Faites ensuite pointer les catégories Hydranos en dessous (par exemple /data/torrents/tv) et la bibliothèque des *arr sous /data/media. Deux montages séparés comme /srv/downloads:/data/downloads et /srv/media:/data/media font échouer tout lien et tout renommage entre eux.

Par défaut, le conteneur tourne en root, et tout ce qu'écrit Hydranos appartient à root.

Réglez PUID et/ou PGID pour tourner sous votre propre utilisateur. L'entrypoint relève d'abord la limite de fichiers ouverts (dans tous les conteneurs, avant tout abandon de privilèges, pour que la limite soit héritée). Ensuite, quand l'une des deux est définie et que le conteneur démarre en root, il :

1. réaffecte le compte hydranos de l'image à cet uid/gid (une valeur manquante vaut 1000 par défaut), ou réutilise un compte ou un groupe qui a déjà cet id ;
2. lance chown -R sur /config (petit : configuration, store, état de reprise). Réglez HYDRANOS_SKIP_CHOWN=1 pour sauter cette étape si les permissions sont déjà bonnes ;
3. démarre hydranos sous cet uid:gid.

/data n'est jamais chowné (il peut contenir des millions de fichiers). Assurez-vous que l'uid/gid peut écrire dans les dossiers vers lesquels pointent vos chemins de sauvegarde.

Si vous démarrez le conteneur avec le --user de Docker, l'entrypoint n'est pas root : il ignore PUID/PGID (en affichant already running as uid <N>, ignoring PUID/PGID quand ils sont définis) et ne peut pas corriger pour vous le propriétaire de /config. L'entrypoint essaie quand même de régler la limite de fichiers ouverts à 1000000, puis 200000 ; si la limite dure n'autorise ni l'une ni l'autre, la limite reste inchangée.

Modes des fichiers. Hydranos ne règle aucun umask et l'image n'a pas de variable UMASK : il hérite donc de l'umask du conteneur (celui de Docker par défaut est 022) : les nouveaux dossiers sont en 755 et les nouveaux fichiers en 644, modifiables par leur seul propriétaire. Si Sonarr ou Radarr doivent renommer ou supprimer des fichiers créés par Hydranos, faites-les tourner avec les mêmes PUID/PGID qu'Hydranos.

Trouver vos ids. Sur un hôte Linux, id -u et id -g (via SSH sur un NAS). Sur Unraid, utilisez 99/100 (voir plus bas). Sur Synology, le premier utilisateur créé a généralement l'uid 1026 et le groupe users est 100, pas 1000 ; vérifiez avec id via SSH si vous le pouvez.

Lues uniquement par entrypoint.sh :

Le démon lui-même lit quelques variables de plus, dont HYDRANOS_STOP_TIMEOUT (le budget d'écriture à l'arrêt, 120 s par défaut, voir Délai de grâce à l'arrêt plus haut), HYDRANOS_LOG_STDOUT et RUST_LOG. Leur analyse exacte est décrite sur Config : environnement, CLI & signaux.

Le dépôt ne fournit aucun template Unraid. Ajoutez le conteneur à la main : onglet Docker → Add Container, passez en vue avancée et remplissez (noms des champs Unraid tels qu'ils apparaissent habituellement ; non testé par le mainteneur) :

99:100 correspond au nobody:users habituel d'Unraid, propriétaire normal des fichiers sur les partages utilisateur. Faites tourner Sonarr et Radarr avec les mêmes ids.

Politique de redémarrage. Le bouton Autostart d'Unraid ne fait généralement que démarrer les conteneurs au boot ; il ne définit pas de politique de redémarrage Docker. Chaque bouton de redémarrage de l'interface web d'Hydranos arrête proprement le processus, le termine avec le code de sortie 75 et compte sur Docker pour le relancer. Sans --restart=unless-stopped, Hydranos reste arrêté après le premier clic de ce genre.

Délai d'arrêt. --stop-timeout=150 règle le délai d'arrêt propre au conteneur, que docker stop utilise quand on ne lui donne pas de -t explicite. Le plafond de taille json-file du fichier compose peut s'ajouter de la même façon (--log-opt max-size=128m --log-opt max-file=5), sauf si vos réglages Docker font déjà tourner les journaux des conteneurs.

Arrêt de l'array. Quand vous arrêtez l'array ou le service Docker, Unraid arrête lui-même les conteneurs et peut appliquer son propre délai plutôt que les 150 s du conteneur (non testé par le mainteneur). Après un arrêt de l'array, vérifiez les dernières lignes du journal avec docker logs hydranos 2>&1 | grep "shutdown flush" : shutdown flush complete signifie que rien n'a été perdu. Si la ligne manque, arrêtez d'abord Hydranos à la main (onglet Docker → Stop, ou docker stop -t 150 hydranos), puis arrêtez l'array. Derrière gluetun, arrêtez Hydranos avant gluetun ; l'ordre n'affecte pas la sauvegarde elle-même, qui n'écrit que dans /config.

Placez /config sur un chemin de pool comme /mnt/cache/appdata/hydranos, pas sur /mnt/user/... (déduit du code, non testé sur Unraid). /mnt/user est la couche FUSE d'Unraid, et Hydranos traite tout montage FUSE comme un système de fichiers réseau, où le mode WAL de SQLite ne peut pas compter sur le verrouillage par mémoire partagée :

• un nouveau store créé là reste en mode rollback-journal de SQLite au lieu de WAL, ce qui ralentit chaque écriture ;
• un store déjà en WAL (créé sur un disque local, puis déplacé) est ouvert tel quel ; si SQLite ne peut pas l'ouvrir là, Hydranos démarre en mode de secours ;
• l'état de reprise de chaque moteur (<engine>/state.db) est mis en WAL où qu'il soit, /mnt/user compris. Rien ne le protège à cet endroit : c'est la raison principale de garder /config sur un chemin de pool.

Un partage « exclusive » d'Unraid (Unraid 6.12 et suivants) est généralement servi sans la couche FUSE et devrait se comporter comme un chemin de pool. Le mappage /data peut, lui, pointer vers un partage utilisateur.

Pour faire tourner Hydranos à l'intérieur d'un conteneur gluetun existant (le mode réseau Gluetun ; le mode WireGuard géré est l'autre voie, voir WireGuard géré), modifiez le template ci-dessus comme suit. Les noms des champs Unraid varient selon les versions ; non testé par le mainteneur.

1. Network Type : Container, puis choisissez gluetun comme réseau de conteneur, si votre version d'Unraid le propose. Sinon, réglez Network Type sur None et ajoutez --net=container:gluetun dans Extra Parameters. Gardez-y --restart=unless-stopped --stop-timeout=150 et l'ulimit.
2. Supprimez toutes les lignes Port du template hydranos. Un conteneur qui partage le réseau d'un autre n'a pas de ports à lui ; Docker refuse d'y publier des ports.
3. Dans le template gluetun, ajoutez à la place les lignes Port : 8199/tcp pour l'interface web et les API, et les ports de pairs. Quel port de pairs ouvrir et comment le régler dans Hydranos (le port redirigé par le VPN) : VPN & sortie réseau.
4. WebUI : le lien [IP]:[PORT:8199] peut ne plus se résoudre une fois que le conteneur n'a plus de ports. Ouvrez directement http://<your-unraid-ip>:8199/ ; il atteint Hydranos via le port publié par gluetun.
5. Sonarr, Radarr et autobrr joignent alors Hydranos à l'adresse d'Unraid sur le port 8199, pas via le nom hydranos.

Le Container Manager de Synology peut créer un Project à partir d'un fichier compose : collez le fichier compose ci-dessus, adaptez les chemins hôte (par exemple /volume1/docker/hydranos pour /config et /volume1/data pour /data) et les ids (voir Trouver vos ids). Passer par un projet conserve stop_grace_period, l'ulimit et le plafond des journaux, que l'assistant de conteneur unique n'expose peut-être pas (non testé par le mainteneur). Créez d'abord les dossiers hôte dans File Station.

Deux voies en 4.4 :

• Dans gluetun. Tout le conteneur Hydranos tourne dans l'espace de noms réseau du conteneur VPN (network_mode: "service:gluetun"), les ports étant publiés sur le conteneur VPN à la place. Avec le mode réseau Gluetun, Hydranos lit le port redirigé sur le serveur de contrôle de gluetun et le suit. La recette, et ce qu'elle protège ou non : VPN & sortie réseau.
• WireGuard géré. Hydranos monte lui-même un tunnel WireGuard par moteur, à partir d'un .conf de fournisseur ; le conteneur a besoin de cap_add: NET_ADMIN (voir les lignes commentées du fichier compose plus haut) : WireGuard géré.

Utilisateurs d'Unraid : voir Unraid derrière gluetun ci-dessus.

Hydranos écrit toujours son journal sur la console, ce qu'affiche docker logs hydranos (ou docker compose logs -f hydranos), plafonné par le bloc logging: ci-dessus.

Il ajoute aussi le même journal à /config/hydranos.log. Ce fichier tourne de lui-même à 128 MiB, en gardant quatre anciens fichiers (hydranos.log.1 à .4), et occupe donc au plus environ 640 MiB. Définir HYDRANOS_LOG_STDOUT avec n'importe quelle valeur, 0 compris, désactive le fichier et ne laisse que la console. Voir Supervision & journaux.

1. Lisez les notes de version dans le changelog.
2. Sauvegardez /config, conteneur arrêté (Exploiter Hydranos).
3. Changez le tag dans votre fichier compose, p. ex. :v4.4.0 → la nouvelle version.
4. docker compose pull && docker compose up -d

Compose arrête l'ancien conteneur avec votre stop_grace_period, l'état de reprise est donc écrit avant que le nouveau démarre. Sur Unraid, modifiez le tag dans Repository et cliquez sur Apply. Rien à l'intérieur du conteneur ne se met à jour tout seul.

Vous venez de la 3.x ? Le nom de l'image a changé : lisez d'abord Mettre à jour depuis la 3.x.

Le docker-compose.yml à la racine du dépôt correspond au code 4.4. Il utilise :latest, qu'une version publiée ne déplace pas : épinglez un tag comme plus haut. Son commentaire « gardez ceci au-dessus de HYDRANOS_STOP_TIMEOUT + 5 s » oublie les 5 s de vidange de l'API ; les 150 s qu'il règle couvrent les deux.

Si quelque chose ne démarre pas, voir Dépannage.

Faites maintenant le Premier démarrage sur Installation & premier démarrage : ouvrez http://<your-docker-host>:8199, créez le compte admin et votre première catégorie. Faites-le avant que le port 8199 soit joignable depuis Internet (Sécurité & accès).