Skip to content

DHT Sidecar Setup

Jump to bottom
o51r15 edited this page Jul 11, 2026 · 1 revision

DHT Sidecar Setup

Run the DHT crawler in a separate container behind gluetun while the main bitmagnet instance stays on the regular Docker network. This avoids the FIREWALL_OUTBOUND_SUBNETS reliability issues and gives the main instance direct access to Prowlarr, Postgres, and your *arr stack.

How it works

bitmagnet's worker architecture supports running individual workers in separate processes. All workers communicate through the shared Postgres database (queue tables, torrent tables). The DHT crawler discovers info_hashes and writes them to the queue. The queue_server in the main container picks them up and handles classification. No direct communication between the two bitmagnet containers is needed.

Setup

Step 1 — Create the shared network:

docker network create bitmagnet-net

Step 2 — Add the shared network to your gluetun compose:

services:
  gluetun:
    image: qmcgaw/gluetun
    cap_add:
      - NET_ADMIN
    ports:
      - "3334:3334/udp"   # DHT port
      - "3334:3334/tcp"
      # ... your existing ports ...
    environment:
      # ... your VPN config ...
    networks:
      - default
      - bitmagnet-net

networks:
  bitmagnet-net:
    external: true

Step 3 — Bitmagnet compose:

services:
  bitmagnet:
    image: ghcr.io/o51r15/bitmagnet:latest
    container_name: bitmagnet
    restart: unless-stopped
    ports:
      - "3333:3333"
    environment:
      - POSTGRES_HOST=postgres
      - POSTGRES_PASSWORD=postgres
      - TMDB_API_KEY=your_key
      - DHT_CRAWLER_SIDECAR_ENABLED=true
      - DHT_CRAWLER_SIDECAR_URL=http://gluetun:3333
    volumes:
      - ./config:/root/.config/bitmagnet
    command:
      - worker
      - run
      - --keys=http_server
      - --keys=queue_server
      - --keys=prowlarr_crawler
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - default
      - bitmagnet-net

  bitmagnet-dht:
    image: ghcr.io/o51r15/bitmagnet:latest
    container_name: bitmagnet-dht
    restart: unless-stopped
    network_mode: "container:gluetun"
    environment:
      - POSTGRES_HOST=bitmagnet-postgres
      - POSTGRES_PASSWORD=postgres
    volumes:
      - ./config:/root/.config/bitmagnet
    command:
      - worker
      - run
      - --keys=dht_crawler
      - --keys=http_server

  postgres:
    image: postgres:16-alpine
    container_name: bitmagnet-postgres
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready"]
      interval: 10s
      start_period: 20s
    networks:
      - default
      - bitmagnet-net

networks:
  bitmagnet-net:
    external: true

Deploy order: gluetun stack first, then bitmagnet stack.

Dashboard status

The sidecar environment variables on the main instance tell it to probe the sidecar for health status:

  • DHT_CRAWLER_SIDECAR_ENABLED=true — enables sidecar mode
  • DHT_CRAWLER_SIDECAR_URL=http://gluetun:3333 — the sidecar's HTTP endpoint

The main instance reaches the sidecar at gluetun:3333 over the shared bitmagnet-net Docker network. No host port mapping is needed — container-to-container communication works directly on shared networks.

The sidecar must run --keys=http_server alongside --keys=dht_crawler to expose the health endpoint that the main instance probes.

When configured correctly, the dashboard shows both "DHT" and "DHT Crawler" as active.

Important notes

Postgres hostname: bitmagnet-dht uses POSTGRES_HOST=bitmagnet-postgres (the container name) because it resolves via the shared external network, not the compose's internal service names. The main bitmagnet uses POSTGRES_HOST=postgres (the service name) since it's in the same compose.

No port conflicts: The sidecar's HTTP server runs on port 3333 inside gluetun's network namespace. The main bitmagnet also uses port 3333 on the host. These don't conflict because they're in different network namespaces. The DHT_CRAWLER_SIDECAR_URL uses http://gluetun:3333 which routes over the Docker network, not through host ports.

Config sharing: Both containers mount the same config directory. The DHT sidecar ignores Prowlarr and OMDb config since it only runs the dht_crawler worker.

Clone this wiki locally