jordyjordy/tracker-tracker repository overview

Self-hosted dashboard for monitoring private tracker stats over time. Track upload, download, ratio, buffer, seedbonus, and rank across all your trackers from one place.

⁠Features

• Per-tracker and fleet-wide stats with 30+ charts
• UNIT3D, Gazelle, GGn, Nebulance, MAM, and AvistaZ network support out of the box
• qBittorrent integration - cross-seed tracking, activity heatmaps, speed history, etc
• Everything stays on your machine. No telemetry, no phoning home.

⁠Screenshots

You can check out a few other, longer, screenshots in the docs folder.

⁠Supported Trackers

Legend:

• ✅ Verified: tested against a live tracker
• 🟡 Unverified: platform adapter exists and should work, but not yet tested.
• 📋 Needs adapter: registry entry exists, but the platform requires a custom adapter that I haven't gotten around to yet
• ⛔ Stuck: trackers I'm not a member of and have no way of implementing
• ❌ Broken: known issue prevents polling (i.e API blocks required endpoints, etc)

⁠Download Clients

⁠Quick Start

⁠Docker (recommended)

mkdir tracker-tracker && cd tracker-tracker

1. Download the compose file and example env:

   curl -LO https://raw.githubusercontent.com/jordanlambrecht/tracker-tracker/main/docker-compose.yml
   curl -L https://raw.githubusercontent.com/jordanlambrecht/tracker-tracker/main/.env.example -o .env
   

   Copy

2. Generate secrets and paste them into .env:

   # Run these, then copy the output into .env
   openssl rand -base64 24   # → POSTGRES_PASSWORD
   openssl rand -base64 48   # → SESSION_SECRET
   

   Copy

3. Start the stack:

   docker compose up -d
   

   Copy

4. Visit http://localhost:3000 to set your master password and start adding trackers.

⁠Updating

docker compose pull && docker compose up -d

The database schema is synced automatically on startup.

⁠Using an external database

If you already run Postgres, remove the tracker-tracker-db service and depends_on block from docker-compose.yml. Set DATABASE_URL in your .env and remove POSTGRES_PASSWORD and POSTGRES_USER.

⁠Local Development

Requires Node.js 24+, pnpm, and PostgreSQL.

pnpm install
cp .env.example .env.local
# In .env.local, set DATABASE_URL to your local Postgres and SESSION_SECRET
pnpm db:push
pnpm dev

Unit tests run with pnpm test:run. The browser smoke suite runs with pnpm test:e2e against a production build (pnpm build first) and a throwaway tracker_tracker_e2e database on the same Postgres server, which it wipes on every run; create that database once with createdb tracker_tracker_e2e and sync it with POSTGRES_DB=tracker_tracker_e2e pnpm db:push.

⁠Configuration

* Set either POSTGRES_PASSWORD (bundled DB) or DATABASE_URL (external DB).

You configure everything else (polling interval, privacy mode, proxy, backups) in the app's Settings page after login.

⁠Data & Volumes

⁠Locked Out? Recovering a Lost Master Password

There is no "forgot password" email. This is a single-user app with no mail server. Instead, the app container ships a recovery command:

docker exec -it tracker-tracker-app tt-recover --check    # can I recover? writes nothing
docker exec -it tracker-tracker-app tt-recover            # dry run, prompts for the new password
docker exec -it tracker-tracker-app tt-recover --apply    # commit

Take a database dump first. It costs seconds and it is the one step you cannot add later:

docker exec tracker-tracker-db sh -c \
  'pg_dump -U "$POSTGRES_USER" tracker_tracker' > tracker-tracker-backup.sql

Do not edit password_hash by hand. Every secret in the database (tracker API tokens, download client credentials, notification configs, your TOTP secret) is encrypted with a key derived from your master password. UPDATE app_settings SET password_hash = ... lets you log in with a key that decrypts nothing, and orphans all of it permanently with no error message. tt-recover recovers the real encryption key, re-encrypts every secret under the new password, clears the lockout counter, and rewrites the hash in a single transaction.

Two things it needs, and one thing it refuses:

• SESSION_SECRET must be byte-identical to what the instance has been running with. It is the only thing that can unwrap the stored encryption key.
• -it on docker exec, so the password can be typed at a hidden prompt instead of landing in your shell history. (--password '<pw>' exists for scripting, but it is visible in ps.)
• If app_settings.encrypted_scheduler_key is NULL (cleared by an emergency lockdown, a nuke, or a failed restore), recovery is impossible and the tool aborts rather than orphaning your data. Restore a dump from before that point.

Lost your authenticator too? Add --disable-totp to clear 2FA in the same transaction.

Full walkthrough, including running against an external database: Lost Master Password⁠.

⁠Adding a Tracker

1. Click + Add Tracker in the sidebar
2. Select from the registry or enter details manually
3. Paste your API token (found in your tracker's security/API settings)
4. The app validates the connection and starts polling automatically

⁠Documentation

Full documentation is available at jordanlambrecht.github.io/tracker-tracker⁠.

Covers installation, tracker setup (UNIT3D, Gazelle, GGn, MAM, AvistaZ), features (proxies, TOTP, backups, download clients, notifications), and troubleshooting.

⁠Contributing

PRs welcome. Areas where help matters most:

• New trackers & missing data: copy src/data/trackers/_template.ts⁠, fill in what you know, and submit a PR. Partial entries are fine. Set draft: true and CI will accept it. Filling in user classes, rules, release groups, and banned groups on existing trackers is just as valuable.
• Download client adapters: only qBittorrent is supported. Deluge, Transmission, and rTorrent all need adapters. See src/lib/download-clients/adapters/qbt.ts for the pattern.
• Tracker verification: if you belong to a tracker marked 🟡 above, testing and confirming it works helps greatly.
• Security auditing: check out SECURITY.md for threat surfice info.
• Responsiveness - I only have my 16" MBP to work off of, so feedback of different screen experiences is much appreciated
• Data Visualization - I ain't no math wizard, so any contributions for data viz, charts/graphs, etc.
• Custom platform adapters: trackers marked "Custom" need bespoke adapters since they don't run a supported platform.

Tracker Tracker is free and independently maintained. GitHub Sponsors⁠ for recurring support, Buy Me a Coffee⁠ for a one-off.

⁠Architecture

• Next.js 16 (App Router)
• PostgreSQL + Drizzle ORM
• ECharts
• node-cron
• Argon2
• jose

⁠License

GPL-3.0⁠