Skip to content

Installation

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

bitmagnet is distributed as a prebuilt Docker image and requires a PostgreSQL 16 container. No Go toolchain or build step is needed.

Prerequisites

TMDB API key — bitmagnet uses The Movie Database for content classification. Get a free key at themoviedb.org/settings/api.

OMDb API key (optional) — enriches movies and TV with Rotten Tomatoes scores, Metacritic ratings, awards, and box office data. Get a free key at omdbapi.com/apikey.aspx.

Prowlarr (optional) — only needed for indexer crawling. Any Prowlarr instance reachable from the bitmagnet container works. See Prowlarr Integration.

Quick start

Step 1 — Create directories and config:

mkdir -p ~/docker/bitmagnet/config
mkdir -p ~/docker/bitmagnet/data

Create ~/docker/bitmagnet/config/config.yml:

dht_crawler:
  scaling_factor: 1
  save_files_threshold: 50
  save_pieces: false
  rescrape_threshold: 720h

processor:
  concurrency: 2

tmdb:
  enabled: true

# Optional: OMDb enrichment
# omdb:
#   enabled: true
#   api_key: your_omdb_key_here

log:
  level: warn

Step 2 — Deploy via Docker 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_tmdb_key_here
      - TZ=UTC
    volumes:
      - ~/docker/bitmagnet/config:/root/.config/bitmagnet
    command:
      - worker
      - run
      - --keys=http_server
      - --keys=queue_server
      - --keys=dht_crawler
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    container_name: bitmagnet-postgres
    restart: unless-stopped
    volumes:
      - ~/docker/bitmagnet/data/postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=bitmagnet
      - PGUSER=postgres
      - TZ=UTC
    healthcheck:
      test: ["CMD-SHELL", "pg_isready"]
      interval: 10s
      start_period: 20s

Via Portainer: Go to Stacks → Add stack, paste the compose, replace API keys, click Deploy.

Via CLI:

docker compose up -d

Step 3 — Enable optional workers by adding keys to the command: block:

command:
  - worker
  - run
  - --keys=http_server
  - --keys=queue_server
  - --keys=dht_crawler
  - --keys=prowlarr_crawler   # optional: Prowlarr indexer crawling
  - --keys=db_trim            # optional: automatic trim of old/dead torrents

See Worker Keys for a full reference.

Updating

Pull the latest image and recreate:

docker compose pull
docker compose up -d

Database migrations run automatically on startup — no manual steps needed.

Next steps

Clone this wiki locally