BitMagnet is a self-hosted torrent search engine and DHT crawler that indexes magnet links from the BitTorrent network. It includes:
- Web UI
- Torrent metadata search
- DHT crawling
- PostgreSQL storage
- Servarr/Prowlarr integration
- GraphQL API
Official project: Bitmagnet GitHub Repository
Official docs: Bitmagnet Documentation
The recommended installation method is Docker Compose.
Requirements
Before installing, make sure your server has:
- Docker
- Docker Compose
- At least:
- 2 CPU cores
- 4 GB RAM
- SSD storage recommended
Docker Compose install docs: Docker Compose Installation Guide
Step 1 — Create Project Folder
mkdir -p ~/bitmagnet
cd ~/bitmagnetStep 2 — Create docker-compose.yml
nano docker-compose.ymlPaste this:
services:
bitmagnet:
image: ghcr.io/bitmagnet-io/bitmagnet:latest
container_name: bitmagnet
ports:
# Web UI
- "3333:3333"
# BitTorrent DHT ports
- "3334:3334/tcp"
- "3334:3334/udp"
restart: unless-stopped
environment:
- POSTGRES_HOST=postgres
- POSTGRES_PASSWORD=postgres
# Optional:
# - TMDB_API_KEY=your_tmdb_api_key
volumes:
- ./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
environment:
- POSTGRES_PASSWORD=postgres
- POSTGRES_DB=bitmagnet
- PGUSER=postgres
volumes:
- ./data/postgres:/var/lib/postgresql/data
shm_size: 1g
healthcheck:
test: ["CMD-SHELL", "pg_isready"]
interval: 10s
start_period: 20sThis configuration is based on the official installation examples.
Step 3 — Start BitMagnet
Run:
docker compose up -dThis will:
- Pull BitMagnet image
- Pull PostgreSQL image
- Create containers
- Start DHT crawling
Step 4 — Verify Containers
Check running containers:
docker psYou should see:
bitmagnetbitmagnet-postgres
Step 5 — Open Web Interface
Visit:
http://YOUR_SERVER_IP:3333Example:
http://192.168.1.50:3333Or locally:
http://localhost:3333The UI should appear within about a minute after startup.
Step 6 — Allow Firewall Ports
If using Ubuntu UFW:
ufw allow 3333/tcp
ufw allow 3334/tcp
ufw allow 3334/udpThen reload:
ufw reloadStep 7 — Check Logs
View live logs:
docker logs -f bitmagnetYou should eventually see crawler activity and indexed torrents appearing.
Optional — Add TMDB Metadata
BitMagnet can enrich movie and TV results using TMDB metadata.
Get API key from:
Then add:
- TMDB_API_KEY=your_key_hereRestart containers:
docker compose restartOptional — Reverse Proxy with Nginx
Example Nginx config:
server {
server_name torrents.example.com;
location / {
proxy_pass http://127.0.0.1:3333;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}Then enable SSL:
certbot --nginxUpdate BitMagnet
docker compose down
docker pull ghcr.io/bitmagnet-io/bitmagnet:latest
docker compose up -dOfficial upgrade instructions match this workflow.
Useful Commands
Stop
docker compose downRestart
docker compose restartView Logs
docker logs -f bitmagnetOpen CLI
docker exec -it bitmagnet bitmagnet