Installation and First Run

Installation & First Run

Docker Compose (recommended)

A ready image is published to GHCR: ghcr.io/kheopsian/hydra. Pin a version (:v3.3.0) for production; :latest tracks main.

services:
  hydra:
    image: ghcr.io/kheopsian/hydra:latest
    container_name: hydra
    restart: unless-stopped
    ports:
      - "8199:8199"        # web UI / API
      - "16171:16171"      # race listen port (forward on your router)
      - "16172:16172"      # hoard listen port
    volumes:
      - ./config:/config   # config, resume data, durable store
      - /path/to/data:/data

Volume convention is /config (singular). The image reads and writes its config, resume data and durable store under /config. Mounting your host folder anywhere else means the container regenerates the admin password and API key on every restart. See Troubleshooting.

First boot

On the first start, with no credentials configured, Hydra:

1. generates a random API key and writes it into default.toml,
2. generates a random admin password, bcrypt-hashes it into [auth], and prints the plaintext once in the logs (level WARN, username=admin password=…).

Grab that password from docker logs hydra, then log in at http://<host>:8199 as admin. You can change it later from the UI (Config → Account). Both are idempotent: a reboot with the hash already set does not regenerate anything.

If you'd rather set the password yourself:

docker run --rm --entrypoint hydra ghcr.io/kheopsian/hydra:latest hash-password 'yourpassword'
# paste the printed bcrypt hash into [auth] password_hash in ./config/default.toml

Adding your first torrent

Use the Add Torrent button in the UI, or point an automation tool at the qBittorrent shim. If the data already exists on disk, read Adding Torrents and Existing Data first — it decides whether Hydra trusts or verifies it.

Build from source

Requires Rust (2021+) and Go 1.25. The multi-stage Dockerfile builds both and is the recommended path; see the README for the manual cargo/go build commands.