marauder

KO | EN

gitlite — search

#python #javascript #hacktoberfest #php #react #reactjs #java #helm #kubernetes #node #nodejs #mongodb

★ 19 Open GitHub ↗

Self-hosted torrent tracker monitor: polls tracker pages, detects new releases, pushes torrents to qBittorrent, Transmission, Deluge or uTorrent

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🦉 Marauder

### *The forum-tracker monitor that stayed up to date.*

**A modern, self-hosted torrent topic monitor for the trackers the *arr stack can't reach.**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/artyomsv/marauder/main/LICENSE)
[![Release: v1.19.2](https://img.shields.io/badge/release-v1.19.2-success.svg)](https://raw.githubusercontent.com/artyomsv/marauder/main/CHANGELOG.md)

[![CI](https://github.com/artyomsv/marauder/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/artyomsv/marauder/actions/workflows/ci.yml)
[![CodeQL](https://github.com/artyomsv/marauder/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/artyomsv/marauder/actions/workflows/codeql.yml)
[![Docker build + scan](https://github.com/artyomsv/marauder/actions/workflows/docker.yml/badge.svg?branch=main)](https://github.com/artyomsv/marauder/actions/workflows/docker.yml)
[![E2E (nightly)](https://github.com/artyomsv/marauder/actions/workflows/e2e.yml/badge.svg)](https://github.com/artyomsv/marauder/actions/workflows/e2e.yml)
[![Client acceptance (nightly)](https://github.com/artyomsv/marauder/actions/workflows/client-acceptance.yml/badge.svg)](https://github.com/artyomsv/marauder/actions/workflows/client-acceptance.yml)
[![Deploy site](https://github.com/artyomsv/marauder/actions/workflows/site.yml/badge.svg)](https://github.com/artyomsv/marauder/actions/workflows/site.yml)

[![Go](https://img.shields.io/badge/backend-Go%201.25-00ADD8.svg)](https://raw.githubusercontent.com/artyomsv/marauder/main/backend/)
[![React 19](https://img.shields.io/badge/frontend-React%2019.2-61DAFB.svg)](https://raw.githubusercontent.com/artyomsv/marauder/main/frontend/)
[![Postgres 18](https://img.shields.io/badge/database-Postgres%2018-336791.svg)](https://raw.githubusercontent.com/artyomsv/marauder/main/deploy/)
[![13 trackers](https://img.shields.io/badge/trackers-13-blue.svg)](https://raw.githubusercontent.com/artyomsv/marauder/main/docs/plugin-development.md)
[![5 clients](https://img.shields.io/badge/clients-5-blue.svg)](https://raw.githubusercontent.com/artyomsv/marauder/main/docs/plugin-development.md)
[![4 notifiers](https://img.shields.io/badge/notifiers-4-blue.svg)](https://raw.githubusercontent.com/artyomsv/marauder/main/docs/plugin-development.md)
[![Torznab+Newznab](https://img.shields.io/badge/Torznab%2BNewznab-supported-success.svg)](https://raw.githubusercontent.com/artyomsv/marauder/main/docs/torznab-newznab.md)
[![Site](https://img.shields.io/badge/marauder.cc-live-a855f7.svg)](https://marauder.cc)

**[marauder.cc](https://marauder.cc)** &middot; [Vision](docs/VISION.md) · [Competitors](docs/COMPETITORS.md) · [PRD](docs/PRD.md) · [Roadmap](docs/ROADMAP.md) · [Changelog](CHANGELOG.md)

</div>

---

## What is Marauder?

Marauder watches torrent tracker topics (RuTracker, LostFilm, Kinozal, NNM-Club,
Anilibria, and friends) for updates and **automatically hands the new
`.torrent` file or magnet link to your torrent client** — qBittorrent,
Transmission, Deluge, uTorrent, or a simple download folder.

It is built in 2026 with a tightly focused set of modern tools:

- **Go** backend — single static binary, ~50 MB image, bounded memory.
- **React 19 + Vite 8 + Tailwind 4 + shadcn/ui** frontend — genuinely modern,
  dark-first, keyboard-friendly.
- **PostgreSQL 18.4** for state.
- **Internal JWT + OIDC (Keycloak / Authentik / any OIDC provider)** for auth.
- **Plugin architecture** for trackers, clients, and notifiers.
- **Sonarr integration** — auto-monitor the updateable forum-tracker topics
  Sonarr grabs but can't keep watching. See
  [docs/sonarr-integration.md](docs/sonarr-integration.md).
- **Configurable tracker domains + mirror fallback** — point a tracker at a
  working mirror when its primary domain is blocked, and Marauder rotates to the
  next mirror automatically on network failures — without recreating a single
  topic. See [docs/tracker-domains.md](docs/tracker-domains.md).
- **Observable** from day one — Prometheus metrics, structured logs,
  `/health`, `/ready`.

<div align="center">
  <img src="site/public/screenshots/mirrors.webp" width="820" alt="Settings — Tracker domains: a per-tracker list where each tracker's active domain and mirrors are configured; LostFilm is expanded showing its domain dropdown, mirror chips, and a Test button." />
  <br />
  <sub><em>Settings → Tracker domains — pick a working mirror per tracker, and Marauder falls back automatically.</em></sub>
</div>

---

## Why another one?

The short version:

> Sonarr, Radarr, and Prowlarr dominate the Torznab/Newznab world. None of
> them can monitor a RuTracker forum thread, because RuTracker isn't a
> Torznab indexer — it's a forum. The Python-era tools that historically
> filled this niche have stalled. Marauder picks up where they left off,
> built on a modern stack with first-class security, observability, and a
> plugin model designed to be easy to extend. And it doesn't compete with
> Sonarr — it integrates: Marauder auto-takes-over monitoring of the forum
> topics Sonarr grabs but can't keep watching.

Read the full rationale: [VISION.md](docs/VISION.md) ·
[COMPETITORS.md](docs/COMPETITORS.md).

---

## Project status

**v1.19.2** — latest release (v1.0.0 was the initial production cut;
v1.0.1 was the first release to publish container images to GHCR).

What works **today**:

- Full stack comes up with `docker compose up -d` and four healthy
  containers (db + backend + frontend + nginx gateway).
- Local username/password login with Argon2id, ES256 JWT, refresh-token
  rotation, master-key-encrypted secrets at rest.
- OIDC sign-in via Keycloak (or any OIDC provider). Bring up the
  bundled Keycloak realm with the `sso` compose profile.
- 13 tracker plugins, 5 torrent-client plugins, 4 notifier plugins.
- In-app cross-tracker search: type a title in the Add-topic form,
  pick a result, monitor it — no browser trip to find the topic URL
  (Rutor, Kinozal, LostFilm, Anilibria public; RuTracker with a
  stored account).
- Generic-magnet → qBittorrent end-to-end pipeline validated against
  a real qBittorrent docker container — see
  [`docs/test-e2e-magnet.md`](docs/test-e2e-magnet.md).
- Cloudflare-bypass sidecar (`cfsolver` profile) for trackers wrapped
  in CF interstitials.
- Audit log, Prometheus metrics, structured JSON logs, system status
  page.
- English + Russian UI.

**Validated end-to-end**: the generic magnet and `.torrent`-URL paths,
the Torznab/Newznab indexer adapters, the **RuTracker**, **LostFilm**
(including interactive captcha login), **Kinozal**, **AniLiberty**
(public API, read-only) and **AniDub** plugins, and **NNM-Club**
(anonymous-only — its login is Cloudflare-Turnstile-gated, so accounts
aren't supported), each against a live target.

What's still **alpha**: the other 3 CIS forum-tracker plugins
(Rutor, Toloka, Tapochek) are structurally complete with fixture-based
tests but have not been validated against live sites — that requires
real account credentials and is the first thing community contributors
will help with.

One of them, **Toloka**, can log in but cannot *confirm* a login: no
reliable signed-in marker has been identified for it, so Marauder saves
the credential and reports it as unverified rather than showing a green
tick it has not earned. Identifying that marker is a good first
contribution — see
[`docs/plugin-development.md`](docs/plugin-development.md).

**Removed 2026-08-03** after every advertised domain was probed:
**HD-Club** (the site shut down in 2017; `hdclub.org` now redirects to
an unrelated file-hosting affiliate site), **Unionpeer** (all three
domains parked or NXDOMAIN) and **Free-Torrents** (no DNS A record).
Existing topics on those trackers will report a missing plugin.

See [CHANGELOG.md](CHANGELOG.md) for the per-plugin status table.

---

## Quick start

> Marauder runs as a Docker Compose stack. The only thing you need on the
> host is Docker — no Go, Node, or Postgres toolchain. Full walkthrough:
> **[docs/getting-started.md](docs/getting-started.md)**.

### Run it — prebuilt images (recommended)

Pull the published, multi-arch, signed images from GitHub Container Registry.
No clone, no local build:

```bash
mkdir marauder && cd marauder

# 1. Compose file + example env
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

# 4. Open http://localhost:34080
```

Requires Docker Compose **v2.23.1+**. Pin the release with `MARAUDER_VERSION`
in `.env` (defaults to `1.19.2`); `latest` also exists.

### Build from source (contributors)

```bash
git clone https://github.com/artyomsv/marauder.git
cd marauder/deploy
cp .env.example .env
sed -i "s|MARAUDER_MASTER_KEY=.*|MARAUDER_MASTER_KEY=$(openssl rand -base64 32)|" .env
docker compose --env-file .env up -d   # first run compiles the images
```

On first start, Marauder creates an admin user from
`MARAUDER_ADMIN_INITIAL_USERNAME` / `MARAUDER_ADMIN_INITIAL_PASSWORD` in the
`.env` file. **Change the password after first login and unset those
variables.**

---

## Architecture at a glance

```
         ┌──────────────┐
         │  React 19    │  shadcn/ui + Tailwind 4 + TanStack Query
         │  frontend    │
         └──────┬───────┘
                │ JSON over HTTPS
                ▼
         ┌──────────────┐       ┌──────────────┐
         │   Go backend │──────►│  PostgreSQL  │
         │   chi + pgx  │       │  18.4        │
         └──┬────┬──────┘       └──────────────┘
            │    │
            │    └──────────┐
            ▼               ▼
     ┌────────────┐   ┌──────────────┐
     │  Tracker   │   │   Torrent    │
     │  plugins   │   │   clients    │
     │ (rutracker,│   │ (qBittorrent,│
     │  lostfilm, │   │  Transmission│
     │  nnm-club, │   │  Deluge,     │
     │   ...)     │   │  ...)        │
     └─────┬──────┘   └──────────────┘
           │
           │ (Cloudflare-protected trackers only)
           ▼
     ┌────────────┐
     │ cfsolver   │  sidecar container: chromium + chromedp
     │ sidecar    │
     └────────────┘

Optional: ────────────────────────────────────────
     OIDC (Keycloak / Authentik / Authelia) for SSO.
     Prometheus + Grafana for metrics.
     Telegram / Email / Webhook / Pushover for notifications.
```

---

## Tech stack

| Layer | Choice | Why |
|---|---|---|
| Backend | Go 1.23+ | Fast, simple concurrency, single binary, mature HTTP/scraping ecosystem, friendly to contributors. See PRD §2. |
| HTTP router | `chi` | Stdlib-idiomatic, middleware composable, minimal. |
| DB driver | `pgx` v5 + `sqlc` | Type-safe queries generated from SQL. |
| Migrations | `goose` | Embedded, runs at startup, simple. |
| Logging | `zerolog` | Structured, allocation-free. |
| Config | `envconfig` | 12-factor, no YAML. |
| Frontend | React 19.2 + TypeScript | Latest stable, Server Components optional. |
| Build | Vite 8.0.2 | Fast HMR, plugin ecosystem. |
| Styling | Tailwind CSS 4.2 | New `@tailwindcss/vite` plugin, no PostCSS headaches. |
| UI kit | shadcn/ui 4.1.2 | Copy-in components, no vendor lock-in. |
| State | TanStack Query v5 + Zustand | Server state + minimal global UI state. |
| Forms | react-hook-form + zod | |
| Database | PostgreSQL 18.4 | |
| Auth | Internal JWT (ES256) + OIDC (Keycloak etc.) | |
| Secrets | AES-256-GCM at rest | |
| Observability | Prometheus + structured JSON logs | |
| Packaging | Docker + docker-compose | No host dependencies. |
| CI | GitHub Actions | Lint, unit, integration, e2e, trivy, govulncheck. |

---

## Repository layout

```
marauder/
├── backend/            Go backend (chi, pgx, sqlc, goose)
├── frontend/           React 19 + Vite 8 + Tailwind 4 + shadcn
├── deploy/             docker-compose files, .env.example, nginx configs
├── docs/               VISION / COMPETITORS / PRD / ROADMAP / guides
├── CHANGELOG.md        Keep a Changelog format
├── LICENSE             MIT
└── README.md
```

---

## Contributing

Marauder is meant to be easy to extend. Adding a new tracker is a single Go
file implementing the [`Tracker`](docs/PRD.md#51-tracker-plugin-contract)
interface plus a recorded-HTTP-fixture test. The full contribution guide is in
[CONTRIBUTING.md](CONTRIBUTING.md) (coming in v0.2).

For now:

- **Open issues** for bugs, feature ideas, or tracker breakage reports.
- **Discuss design** before large PRs — a quick issue saves a lot of rebasing.
- **Don't** submit PRs adding hard-coded tracker URLs pointing at copyrighted
  content. Marauder is an automation tool, not an index.

---

## License & credits

Marauder is released under the [MIT License](LICENSE).

Built inspired by [monitorrent](https://github.com/werwolfby/monitorrent) — the
project that pioneered the forum-tracker monitoring niche. Marauder is an
independent, ground-up implementation, but the problem statement and the user
experience it targets are owed to that earlier work.

---

## Legal notice

Marauder is a general-purpose automation tool. It does not host content and
does not ship with any pre-configured tracker URLs. What you choose to
monitor and download is **your responsibility** and subject to the laws of
your jurisdiction and the terms of service of the trackers you use.

marauder

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README