Deployment Topologies FR

🇬🇧 English · 🇫🇷 Français

Topologies de déploiement

Hydra tourne sous trois formes. Les trois parlent la même UI/API ; la différence est où vivent les moteurs.

Monolithe (par défaut)

Un process, race + hoard locaux. Le plus simple, un conteneur. À utiliser dès que tu contrôles de vrais ports inbound (forward sur ta box maison, ou un VPS) : race et hoard bindent et forwardent chacun leur port.

Agent (--agent-only)

Un nœud headless hébergeant un ou plusieurs moteurs, exposé en gRPC (token + TLS) pour qu'un front distant le pilote. Pas d'UI locale. Sert à placer des moteurs sur d'autres machines.

Front-only (--front-only)

Une UI/contrôleur sans moteur local. Il dial les agents distants et les agrège en un seul dashboard, une seule liste de torrents, une seule surface d'ajout/routage.

Sharder un monolithe

Un monolithe peut aussi enregistrer des agents distants et ajouter des moteurs locaux supplémentaires pour répartir la charge — via l'UI (Agents → Local engines) ou des blocs [[engine]] dans la config. Chaque moteur a un id et un rôle (race/hoard) ; tu peux faire tourner, par exemple, un race + plusieurs hoard sur une machine.

Choisir un déploiement

• Tu contrôles de vrais ports inbound (box maison, ou VPS) → monolithe. race et hoard forwardent chacun leur port. Un conteneur, terminé.

• Tu es derrière un VPN qui ne forwarde qu'un port (gluetun + Proton / PIA / …) → ne fourre pas les deux moteurs dans un seul tunnel (un port ne peut servir deux moteurs). À la place :

  • un contrôleur front-only, plus
  • un --agent-only par moteur, chacun dans son propre gluetun, pour que chaque moteur ait son port forwardé.

  Le UP_COMMAND gluetun de chaque agent pousse son port qui tourne à son moteur local, et le nœud front-only les agrège et les pilote depuis une seule UI. Voir Gluetun (VPN).

Voir Catégories & routage pour comment les nouveaux torrents sont placés sur les moteurs/agents.

Le lancer (Docker Compose)

Les flags qui choisissent la forme sont sur le binaire hydra :

Flag	Où	Sens
(aucun)	monolithe	race + hoard local, UI + API complètes
--front-only	contrôleur	UI/API, aucun moteur ; dial les [[agent]] de la config
--agent-only	agent	moteurs + data-plane gRPC, aucune API HTTP
--agent-addr :9090	agent	obligatoire avec --agent-only — adresse d'écoute gRPC
--agent-token <tok>	agent/front	token partagé (le front l'envoie, l'agent le vérifie)
--agent-tls-cert / --agent-tls-key	agent	TLS pour le data-plane gRPC
--listen-port-hook <port>	agent	opt-in : POST /listen-port loopback-only pour qu'un gluetun du même netns pousse le port forwardé (voir plus bas)

Monolithe derrière un seul VPN

Le plus simple quand un seul moteur a besoin d'entrant. Hydra tourne dans le netns de gluetun ; gluetun pousse le port forwardé (qui tourne) vers l'endpoint natif (/api/hoard/listen-port, auth X-API-Key) — pas le shim qBit.

services:
  gluetun:
    image: qmcgaw/gluetun
    cap_add: [NET_ADMIN]
    devices: [/dev/net/tun]
    environment:
      VPN_SERVICE_PROVIDER: protonvpn
      VPN_TYPE: wireguard
      # ... vos identifiants WIREGUARD_* ...
      VPN_PORT_FORWARDING: "on"
      FIREWALL_INPUT_PORTS: "8199"          # laisser le LAN joindre l'UI
      VPN_PORT_FORWARDING_UP_COMMAND: >
        /bin/sh -c 'wget -qO- --header="X-API-Key: ${HYDRA_API_KEY}"
        --post-data "{\"port\":{{PORTS}}}"
        http://127.0.0.1:8199/api/hoard/listen-port'
    ports:
      - "8199:8199"                          # UI, publiée via gluetun
    restart: unless-stopped

  hydra:
    image: ghcr.io/kheopsian/hydra:latest
    network_mode: "service:gluetun"
    depends_on: [gluetun]
    volumes:
      - ./config:/config
      - /path/to/data:/data
    restart: unless-stopped

HYDRA_API_KEY = la clé de ./config/default.toml (affichée une fois au 1er boot — voir Installation & premier lancement).

Front-only + un agent par moteur (VPN à port unique, recommandé)

Un tunnel VPN forwarde un port, qui ne peut pas servir deux moteurs. Donne à chaque moteur son propre gluetun, lance-le en --agent-only, et agrège le tout depuis un contrôleur --front-only. Chaque agent active le --listen-port-hook pour que son gluetun pousse son port forwardé — sinon l'agent n'a aucune API HTTP.

services:
  # ---- Agent HOARD, derrière son propre VPN ----
  gluetun-hoard:
    image: qmcgaw/gluetun
    cap_add: [NET_ADMIN]
    devices: [/dev/net/tun]
    environment:
      VPN_SERVICE_PROVIDER: protonvpn
      VPN_TYPE: wireguard
      # ... vos identifiants WIREGUARD_* ...
      VPN_PORT_FORWARDING: "on"
      FIREWALL_INPUT_PORTS: "9090"          # laisser le front joindre le data-plane gRPC
      VPN_PORT_FORWARDING_UP_COMMAND: >
        /bin/sh -c 'wget -qO- --header="X-API-Key: ${AGENT_TOKEN}"
        --post-data "{\"port\":{{PORTS}}}"
        http://127.0.0.1:9091/listen-port'
    ports:
      - "9090:9090"                          # gRPC HydraAgent, joint par le front
    restart: unless-stopped

  hydra-agent-hoard:
    image: ghcr.io/kheopsian/hydra:latest
    network_mode: "service:gluetun-hoard"
    depends_on: [gluetun-hoard]
    command: >
      hydra --config /config/default.toml
            --agent-only
            --agent-addr :9090
            --agent-token ${AGENT_TOKEN}
            --listen-port-hook 9091
    volumes:
      - ./agent-hoard:/config
      - /path/to/data:/data
    restart: unless-stopped

  # ---- Contrôleur front-only (aucun moteur) ----
  hydra-front:
    image: ghcr.io/kheopsian/hydra:latest
    command: hydra --config /config/default.toml --front-only
    ports:
      - "8199:8199"                          # l'unique UI pour tout
    volumes:
      - ./front:/config
    restart: unless-stopped

./agent-hoard/default.toml — un seul moteur pour que le port unique du tunnel le serve :

[[engine]]
id   = "hoard"
role = "hoard"

./front/default.toml — le front dial l'agent via le port publié du gluetun :

[[agent]]
addr   = "gluetun-hoard:9090"
token  = "meme valeur que AGENT_TOKEN"
tls_ca = ""            # chemin du CA si tu actives --agent-tls-cert/-key sur l'agent

Notes :

• Deux ports distincts sur l'agent : 9090 = data-plane gRPC, publié pour que le front l'atteigne ; 9091 = le hook loopback, jamais dans ports: — bindé sur 127.0.0.1 en dur, joignable uniquement depuis le netns partagé (gluetun + l'agent), jamais via le VPN ni le LAN.
• Ajouter un moteur race = dupliquer le couple (gluetun-race + hydra-agent-race) avec son port gRPC (ex 9092), son hook (9093), une config [[engine]] id="race" role="race", et un 2e bloc [[agent]] sur le front.
• Voir Gluetun (VPN) pour les détails de port-forwarding par fournisseur.