🇬🇧 English · 🇫🇷 Français

S'applique à Hydranos 4.4.

Cette page s'adresse à toute personne qui installe Hydranos pour la première fois, quelle que soit la plateforme. Elle liste ce dont vous avez besoin et les ports à ouvrir, vous aide à choisir entre Docker, Linux et Windows, puis déroule le premier démarrage, identique partout : créer le compte admin, trouver votre clé API, créer une catégorie, ajouter un torrent et vérifier que tout fonctionne.

• Un dossier pour la configuration et l'état. Hydranos écrit son fichier de configuration (default.toml), l'état de reprise de chaque moteur et son fichier journal (hydranos.log) dans le dossier de configuration. Le store (hydra.db) va dans le dossier de données ([daemon] data_dir) : le même dossier sous Docker, /var/lib/hydranos avec le script Linux fourni, data à côté du fichier de configuration sous Windows. Gardez les deux sur un disque local.
• Un dossier (ou un montage) pour les données des torrents. Hydranos n'a aucun chemin de sauvegarde par défaut : chaque torrent va dans le chemin de sauvegarde (save path) de sa catégorie, ou dans un chemin que vous donnez explicitement. Ce dossier doit seulement exister et être accessible en écriture par le processus.
• Des ports ouverts, listés ci-dessous.

Les pages par plateforme indiquent où se trouvent ces dossiers sur chaque plateforme. Architecture explique le rôle de chaque fichier.

Les valeurs viennent du fichier de configuration : [daemon] api_port, [race] listen_port, [hoard] listen_port. Par défaut (auto_port_forward = true), Hydranos demande aussi à votre routeur de rediriger chaque port de moteur, TCP et UDP (NAT-PMP, puis UPnP ; NAT-PMP sous Linux uniquement). Quand le routeur ne répond pas, redirigez les deux à la main. Détails sur Réseau : ports & redirection.

Les trois font tourner le même binaire hydranos, avec la même interface web, les mêmes API et les mêmes moteurs. Choisissez celle qui correspond à la machine que vous avez déjà.

Sur toutes les plateformes, un arrêt propre vide l'API (5 s au plus ; les onglets ouverts de l'interface web ferment eux-mêmes leurs connexions actives), signale aux trackers que chaque moteur s'en va (5 s au plus), puis écrit l'état de reprise de chaque moteur dans le délai HYDRANOS_STOP_TIMEOUT (120 s par défaut) avant de quitter. Un redémarrage depuis l'interface web suit le même chemin et quitte avec le code 75, pour que le superviseur (la politique de redémarrage de Docker, le Restart=on-failure de systemd) le relance ; sous Windows, le processus lance lui-même son successeur. Un kill qui ne l'attend pas (le SIGKILL de Docker après le délai de grâce, un timeout systemd, la fin de tâche dans le Gestionnaire des tâches) saute cette écriture ; voir Exploiter Hydranos.

Guides d'installation, sans ordre de préférence :

• Docker : Compose, Unraid, PUID/PGID.
• Linux (bare metal) : archive de release et systemd.
• Windows : zip, icône dans la zone de notification, lancement avec Windows.

Revenez ici pour le Premier démarrage une fois le processus lancé.

Au tout premier lancement, Hydranos écrit un fichier de configuration de départ s'il n'en existe pas, génère une clé API et la stocke dans ce fichier, et ouvre aussitôt le port 8199. Pendant que les moteurs chargent leurs torrents, la page affiche un écran de démarrage (HYDRANOS, une phase comme Restauration de l'état… (Restoring state…), Connexion au réseau… (Connecting to the network…), Ouverture de la base… (Opening the database…) ou Démarrage… (Starting…), et <restored> / <total> torrents) et laisse la place à la page normale d'elle-même ; sur une installation neuve, cela prend quelques secondes. D'ici là, la connexion répond 503 avec Retry-After: 5, et la création du compte (POST /api/setup) est refusée : le routeur de démarrage ne route que GET /api/setup pendant le chargement des torrents. Si Créer le compte (Create account) échoue pendant l'écran de démarrage (une erreur comme Setup failed (<status>) ou Hydranos is starting …), attendez que l'écran de démarrage disparaisse et réessayez. Aucun compte admin et aucun mot de passe n'existent encore. Rien n'affiche de « mot de passe admin temporaire » : vous créez le compte vous-même dans le navigateur.

Ouvrez http://<host>:8199 (par exemple http://192.0.2.10:8199, ou http://localhost:8199 sur la même machine).

sequenceDiagram
    participant B as Navigateur
    participant H as hydranos sur le port 8199
    B->>H: GET /
    H-->>B: page de l'interface web
    B->>H: GET /api/setup
    H-->>B: needs_setup = true (pas encore de password_hash)
    Note over B: écran Bienvenue dans Hydranos
    B->>H: POST /api/setup avec nom d'utilisateur et mot de passe
    alt torrents encore en chargement
        H-->>B: refusé, le routeur de démarrage ne route que GET /api/setup
    else appelant hors loopback et hors réseau privé
        Note over H: d'abord le pair de la socket, puis la première adresse X-Forwarded-For
        H-->>B: 403 first-run setup only answers a local caller, run hydranos reset-password on the host
    else mot de passe de moins de 8 caractères
        H-->>B: 400 password must be at least 8 characters
    else accepté
        H->>H: écrit [auth] username et password_hash dans default.toml
        H-->>B: 200 avec status ok, username, api_key
    end
    Note over B: clé API stockée dans ce navigateur, la page se recharge
    B->>H: les appels API suivants portent l'en-tête X-Api-Key
    B->>H: tout POST /api/setup ultérieur
    H-->>B: 409 admin account already configured

La page affiche Bienvenue dans Hydranos (Welcome to Hydranos) avec le texte Créez votre compte administrateur pour commencer. (Create your admin account to get started.)

1. Choisissez une Langue (Language) si vous le souhaitez (cela recharge la page).
2. Nom d'utilisateur (Username) est prérempli avec admin ; changez-le si vous voulez. Un nom vide devient aussi admin.
3. Tapez un mot de passe dans Mot de passe (8 caractères min.) (Password (min 8 characters)) puis à nouveau dans Confirmer le mot de passe (Confirm password). Moins de 8 caractères est refusé.
4. Cliquez sur Créer le compte (Create account).

Si data_dir (là où vit le store) est sur un stockage réseau, le même écran affiche un avertissement (Configuration détectée sur un stockage réseau … (Config on network storage detected …)) : la base ne peut pas y utiliser son mode de journal le plus sûr ; gardez des sauvegardes de votre data_dir, ou déplacez-le sur un disque local.

Hydranos écrit le nom d'utilisateur et un hachage bcrypt du mot de passe dans la section [auth] de default.toml, transmet la clé API au navigateur et recharge la page. Il y a un seul compte admin ; il n'y a pas d'autres utilisateurs. La prochaine fois qu'un navigateur n'a pas de clé, il affiche Hydranos login et échange votre nom d'utilisateur et votre mot de passe contre la clé.

Sur une instance neuve, une fenêtre Import an existing library (qBittorrent / Transmission) peut s'ouvrir d'elle-même après le rechargement. Cliquez sur Passer (Skip) dans les deux cas. Si vous migrez depuis qBittorrent, lisez Votre clé API et N'exposez pas le port 8199 ci-dessous, puis suivez Migrer depuis qBittorrent au lieu des sections Créer votre première catégorie et Ajouter votre premier torrent : cette page vous dit quelles catégories créer pour qu'elles correspondent à votre ancien client.

Envie d'un autre mot de passe plus tard ? Utilisez la carte Changer le mot de passe (Change password) sous Config (8 caractères au moins ; vous restez connecté). Mot de passe perdu ? Lancez hydranos reset-password '<password>' [path/to/default.toml] sur l'hôte, puis redémarrez Hydranos. Détails par plateforme sur Sécurité & accès.

La clé API est l'identifiant principal pour l'API REST, le shim qBittorrent (comme alternative au mot de passe admin) et le serveur MCP ; un cookie de session obtenu par une connexion nom d'utilisateur/mot de passe est accepté sur les mêmes routes. Elle fait 48 caractères hexadécimaux, est générée au premier démarrage quand [daemon] api_key est vide (ou contient encore la valeur d'exemple publiée change-me-in-production), et est écrite dans default.toml.

Pour la voir : Config › Paramètres avancés (default.toml) (Advanced settings (default.toml)) › Général (General) › api_key (avec un bouton de copie). Vous pouvez aussi la lire dans le fichier de configuration. Envoyez-la dans l'en-tête X-Api-Key :

curl -H "X-Api-Key: YOUR_API_KEY" http://192.0.2.10:8199/api/categories

Les exemples curl de cette page sont écrits pour un shell Linux ou macOS. Sous Windows, tapez curl.exe (dans PowerShell, curl tout court est une autre commande) et mettez toute la commande sur une seule ligne, sans les \ de fin de ligne.

Si Hydranos ne peut pas écrire le fichier de configuration, la clé reste telle quelle : vide (chaque appel authentifié est refusé avec 401) ou, si le fichier contient encore la valeur d'exemple publiée change-me-in-production, cette valeur publique continue de fonctionner. Corrigez les permissions du fichier et redémarrez.

Tant que le compte admin n'existe pas, le premier appelant qui passe la vérification « appelants locaux uniquement » peut le créer et recevoir la clé API. La vérification regarde d'abord l'adresse d'où vient la connexion : une adresse publique est refusée (403), quels que soient les en-têtes envoyés. Une connexion depuis le loopback ou un réseau privé passe, sauf si elle porte un en-tête X-Forwarded-For dont la première adresse est publique. Deux conséquences :

• un reverse proxy sur votre réseau qui n'envoie pas X-Forwarded-For (ou tout autre élément qui réécrit la source en adresse privée) fait passer chaque appelant pour local ;
• un client sur une adresse VPN hors des plages privées, comme le 100.64.0.0/10 de Tailscale, est refusé : créez le compte depuis le réseau local ou la machine elle-même, ou utilisez hydranos reset-password sur l'hôte.

Créez donc le compte depuis votre réseau domestique (ou depuis la machine elle-même) avant de rediriger le port 8199 ou de le mettre derrière un reverse proxy public. Détails sur Sécurité & accès.

Vous migrez depuis qBittorrent ? Sautez cette section et la suivante ; suivez plutôt Migrer depuis qBittorrent.

Un torrent sans chemin de sauvegarde est refusé (no save path: category "…" is unknown and no savepath was given), et il n'y a pas de dossier par défaut. Le moyen le plus simple de donner un chemin de sauvegarde à chaque torrent est une catégorie : un nom, un Mode (race ou hoard, qui choisit le moteur) et un Chemin d'enregistrement (Save Path).

Dans l'interface web :

1. Ouvrez l'onglet Catégories (Categories) et cliquez sur + Nouveau (+ New).

2. Nom (Name) : par exemple movies.

3. Mode : dans le doute, choisissez Hoard. Hoard sert aux torrents que vous gardez, et le drain race n'y touche jamais. Race sert à faire la course sur les uploads frais, et son drain automatique peut supprimer des torrents avec leurs données quand un disque se remplit. Les torrents importés depuis qBittorrent atterrissent aussi dans hoard. La différence est expliquée sur Moteurs : race & hoard.

4. Chemin d'enregistrement : un dossier où le processus peut écrire, tel que Hydranos le voit :

   Plateforme	Exemple de chemin de sauvegarde
   Docker	/data/movies (dans le conteneur, sur votre montage /data)
   Linux	/srv/torrents/movies
   Windows	D:\Torrents\movies

5. Laissez Passer vers (catégorie Hoard) (Graduate to (hoard category)) vide pour l'instant, et cliquez sur Enregistrer (Save).

La même chose avec l'API REST (répond 201 avec la catégorie) :

curl -X POST http://192.0.2.10:8199/api/categories \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"movies","mode":"hoard","save_path":"/srv/torrents/movies"}'

Remplacez /srv/torrents/movies par le chemin de sauvegarde de votre plateforme, d'après le tableau ci-dessus.

Le mode doit être race ou hoard (casse indifférente) ; toute autre valeur est refusée avec 400 (mode must be race or hoard, not "…"). Les catégories, les tags et la règle de placement complète sont sur Catégories & routage.

1. Ouvrez l'onglet + Ajouter un torrent (+ Add Torrent).
2. Choisissez votre catégorie dans Catégorie (Category). Son chemin de sauvegarde et son mode s'appliquent automatiquement.
3. Sélectionnez un fichier sous Ou envoyer un .torrent (Or Upload .torrent) (plusieurs fichiers sont acceptés). Avec Prévisualiser le contenu avant d'ajouter (Preview contents before adding) coché, la colonne de droite affiche les fichiers et les trackers, lus dans votre navigateur.
4. Cliquez sur Ajouter un torrent (Add Torrent).

Une ligne verte le confirme (Added … pour un fichier, N torrents ajoutés (N torrents added) pour plusieurs). Le torrent apparaît ensuite sur l'onglet Race ou l'onglet Hoard, selon le mode de la catégorie. Si des fichiers de ce torrent existent déjà dans le chemin de sauvegarde, Hydranos les vérifie d'abord par hachage et ne télécharge que ce qui manque ; sinon il télécharge tout.

Ne touchez pas pour l'instant à la section Avancé : forcer le mode et le chemin (Advanced, override mode & save path) : ses champs (Chemin d'enregistrement, Mode, Put the payload in its own subfolder, Skip the hash check, the data is already on disk, Add without starting) remplacent ce que décide la catégorie. Les magnets, les dossiers surveillés, le seed de données existantes sans vérification par hachage, et ces champs sont traités sur Ajouter des torrents & données existantes.

Le même envoi avec l'API REST :

curl -H "X-Api-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "category=movies" \
  http://192.0.2.10:8199/api/torrents/upload

Le champ de fichier peut s'appeler file, torrent ou torrents ; les trois sont acceptés. La réponse est {"info_hash":"…","name":"…","engine":"hoard","mode":"hoard"} en cas de succès (engine est le moteur où le torrent est allé, mode le rôle de ce moteur), 409 avec {"error":"…"} quand le torrent est déjà ajouté, ou 400 avec {"error":"…"}.

• Chiffres de l'en-tête : l'en-tête affiche la version, les débits Envoi (Upload) et Téléchargement (Download), et, dans une fenêtre de largeur bureau, IP de sortie (Exit IP), l'adresse publique sous laquelle les moteurs sont vus (cliquez dessus pour la rafraîchir).

• Point de terminaison de santé, sans clé :

  curl http://192.0.2.10:8199/health

  Il répond un JSON dont le status vaut starting (chargement en cours), healthy, degraded (un moteur sans son écoute, bloqué par le kill switch ou retenu), tous avec HTTP 200, ou unhealthy avec HTTP 503 (le store ne répond pas, ou aucun moteur n'écoute les pairs). Le corps porte aussi version, uptime, checks et problems ; voir Supervision & journaux.

• Journaux : l'onglet Journaux (Logs) affiche les lignes récentes, avec des filtres par module, niveau, période et texte, et un suivi En direct (Live). Les mêmes lignes vont dans hydranos.log dans le dossier de configuration (/config/hydranos.log sous Docker, /etc/hydranos/hydranos.log avec le script Linux fourni, C:\Hydranos\hydranos.log sous Windows avec la configuration dans C:\Hydranos\default.toml) ainsi que dans la console ou docker logs. Cherchez les lignes hydra API listening (starting) puis hydra API ready, et un avertissement indiquant qu'une nouvelle clé API a été générée au premier démarrage. Le fichier tourne de lui-même à 128 MiB et garde quatre anciens fichiers.

• Pairs : au bout de quelques minutes, un torrent en téléchargement affiche des pairs et un débit de téléchargement. S'il reste à zéro, vérifiez les ports des moteurs ci-dessus et Dépannage.

• Remplacer qBittorrent derrière Sonarr/Radarr : Migrer depuis qBittorrent.
• Découvrir les écrans : Visite de l'interface web.
• Organiser où vont les torrents : Catégories & routage.
• Ajouter des magnets, des dossiers surveillés ou des données que vous avez déjà : Ajouter des torrents & données existantes.
• Avant d'exposer quoi que ce soit sur Internet : Sécurité & accès.
• Quelque chose ne marche pas : Dépannage.