Install Marauder in 5 minutes

Prerequisites

• • A Linux, macOS, or Windows host with Docker 24+ and Docker Compose v2.23.1+
• • openssl for generating the master encryption key
• • git only if you build from source (Option B)
• • Optional: an existing torrent client (qBittorrent / Transmission / Deluge) running somewhere reachable from the host

Option A — prebuilt images (recommended)

Pull the published, multi-arch, cosign-signed images from GitHub Container Registry. No clone, no local build — the compose file ships the gateway config inline, so it's the only thing you download.

mkdir marauder && cd marauder

# 1. Compose file + example env (no git clone needed)
curl -fsSLO https://raw.githubusercontent.com/artyomsv/marauder/main/deploy/docker-compose.ghcr.yml
curl -fsSL  https://raw.githubusercontent.com/artyomsv/marauder/main/deploy/.env.example -o .env

# 2. Generate the required 32-byte master key
sed -i "s|MARAUDER_MASTER_KEY=.*|MARAUDER_MASTER_KEY=$(openssl rand -base64 32)|" .env

# 3. Pull + start
docker compose -f docker-compose.ghcr.yml --env-file .env up -d

Then open http://localhost:34080. Pin the release with MARAUDER_VERSION in .env (defaults to 1.11.0); latest also exists.

Option B — build from source

For contributors and anyone running an unreleased commit. Docker compiles the backend, frontend, and cfsolver images locally on first start.

git clone https://github.com/artyomsv/marauder.git
cd marauder/deploy
cp .env.example .env

# generate the master key, then build + start (first run compiles images)
sed -i "s|MARAUDER_MASTER_KEY=.*|MARAUDER_MASTER_KEY=$(openssl rand -base64 32)|" .env
docker compose --env-file .env up -d

Option C — Kubernetes (advanced)

Deploy to your own cluster. A single Helm chart is the source of truth, with derived Kustomize overlays and pre-rendered plain manifests — use whichever you prefer. Pick a database tier: simple (one Postgres pod) or cnpg (CloudNativePG with failover and Barman → S3 point-in-time backups).

git clone https://github.com/artyomsv/marauder.git

# Simple tier (single Postgres pod). Helm chart is the source of truth.
helm install marauder marauder/deploy/helm/marauder \
  -n marauder --create-namespace \
  -f marauder/deploy/helm/marauder/values-simple-db.yaml \
  --set persistence.downloads.type=pvc \
  --set persistence.downloads.pvc.storageClass=YOUR_SC \
  --set database.simple.persistence.pvc.storageClass=YOUR_SC \
  --set secrets.masterKey="$(openssl rand -base64 32)" \
  --set secrets.dbPassword="$(openssl rand -base64 24)" \
  --set initialAdmin.password="change-me"

# Reach the UI (gateway defaults to ClusterIP):
kubectl -n marauder port-forward svc/marauder-gateway 34080:80

Every volume (DB data, app config, downloads/media) takes a uniform type — existingClaim, pvc, nfs, hostPath, emptyDir, or a raw escape hatch — so you decide how storage is provided. The gateway defaults to a ClusterIP Service, so the chart is load-balancer-agnostic (LoadBalancer, NodePort and Ingress are opt-in). Optional bundled torrent clients and a Sonarr/Prowlarr/FlareSolverr stack are a values toggle away.

Full details — the CNPG tier, the volume menu with per-backend examples, exposure options, secrets, and the Kustomize / plain-manifest paths — are in the Kubernetes deployment guide.

The master key

Marauder encrypts every secret it stores (tracker credentials, client configs, JWT signing keys) with AES-256-GCM keyed by a 32-byte master key you supply via MARAUDER_MASTER_KEY. The commands above generate one for you.

Save the key somewhere safe. Losing it means every stored credential is unrecoverable.

Verify it's healthy

The stack is ready when /health returns 200 and /api/v1/system/info reports the version.

curl -fsS http://localhost:34080/health
# .

curl -sS http://localhost:34080/api/v1/system/info | jq .version
# {
#   "version": "1.11.0",
#   "commit":  "...",
#   "buildDate": "..."
# }

Sign in and add your first topic

Open http://localhost:34080, sign in as admin / pleasechangeme, then change the password from Settings. Use the Add topic button to paste a magnet link or tracker URL, configure a torrent client under Clients, set it as default, and Marauder will hand future updates straight to it.

Or, from the command line:

curl -sS -X POST http://localhost:34080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"pleasechangeme"}'

Next steps