Skip to content

Gluetun VPN Deployment

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

Gluetun VPN Deployment

If you want DHT traffic routed through a VPN, there are two approaches depending on your network setup.

Option 1 — Single compose with gluetun

The simplest approach puts bitmagnet and gluetun in the same compose file. Bitmagnet runs under gluetun's network namespace so all traffic (DHT, TMDB, etc.) goes through the VPN. Postgres stays on its own bridge network so a VPN hiccup doesn't take the database offline.

Use gluetun's FIREWALL_OUTBOUND_SUBNETS to allow bitmagnet to reach local services (Prowlarr, *arr stack) on your LAN:

services:
  gluetun:
    image: qmcgaw/gluetun
    cap_add:
      - NET_ADMIN
    ports:
      - "3333:3333"       # bitmagnet WebUI
      - "3334:3334/udp"   # DHT
      - "3334:3334/tcp"   # DHT
    environment:
      - FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24
      # ... your VPN provider config ...
    networks:
      - bitmagnet_internal

  bitmagnet:
    image: ghcr.io/o51r15/bitmagnet:latest
    network_mode: "service:gluetun"
    environment:
      - POSTGRES_HOST=postgres
      - POSTGRES_PASSWORD=postgres
      - TMDB_API_KEY=your_key
    volumes:
      - ./config:/root/.config/bitmagnet
    command:
      - worker
      - run
      - --keys=http_server
      - --keys=queue_server
      - --keys=dht_crawler
      - --keys=prowlarr_crawler
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    networks:
      - bitmagnet_internal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  bitmagnet_internal:
    driver: bridge

This works for most users. VPN outages cause DHT and TMDB timeouts (logged as warnings) but bitmagnet keeps running because Postgres is on a separate bridge.

Critical: Do NOT put Postgres on network_mode: service:gluetun. When gluetun loses VPN connectivity, it takes Postgres offline too, causing crash loops. Always give Postgres its own network.

Option 2 — Split worker sidecar (separate gluetun compose)

If gluetun's FIREWALL_OUTBOUND_SUBNETS doesn't reliably allow access to your local network — which can happen depending on your Docker host, network topology, or VPN provider — use a split sidecar deployment instead.

The main bitmagnet container runs on the normal Docker network with full access to Postgres, Prowlarr, and your *arr stack. A second container runs only the DHT crawler under gluetun's network namespace. Both share the same Postgres database.

See DHT Sidecar Setup for the full compose and configuration.

Postgres network topology

The key principle: Postgres must never depend on gluetun's network. Use a dedicated bridge network (bitmagnet_internal or bitmagnet-net) that both Postgres and bitmagnet connect to. This ensures database connectivity survives VPN outages.

Common issues

TMDB timeouts under VPN: TMDB API calls route through the VPN exit node. If that node has poor routing to TMDB's CDN, classification timeouts spike. The classifier automatically disables TMDB temporarily after repeated failures and re-enables when connectivity returns. Try a different VPN server country if this persists.

DHT bootstrap DNS failures: gluetun routes DNS through the VPN. When VPN is unstable, DNS for DHT bootstrap nodes times out. This shows as WARN in logs and triggers automatic reseed. Recovers on its own once DNS resolves — not a crash condition. Ignore unless the ktable stays empty for more than 10 minutes.

Clone this wiki locally