Self-hosted torrent search and download helper. Search RuTracker, cache results locally, fetch covers, and monitor downloads in qBittorrent — from one UI.
Intended for personal / local use. Sign-in is always required. Without
OIDC_CLIENT_ID, the first visitor registers with email/password (then login-only). With OIDC configured, any OpenID Connect IdP is used instead — Authentik is documented as a local example in docker/AUTHENTIK.md. Do not expose the app without TLS.
- Local-first search — query cached torrents in Postgres (
pg_trgm), fall back to live RuTracker when needed - Cover images — background fetch + MinIO/S3 storage
- qBittorrent — live status over WebSocket subscriptions
- In-app settings — RuTracker credentials, proxy, qBittorrent URL / API key
- Cloudflare bypass — Byparr (FlareSolverr-compatible) for RuTracker access
| Layer | Tech |
|---|---|
| Monorepo | Bun workspaces + Turborepo |
| Backend | Bun, tRPC, Drizzle ORM, Postgres, MinIO |
| Frontend | React 19, TanStack Router/Query, Vite, Astryx |
| Tracker client | @brotracker/rutracker-ts (workspace package) |
apps/
backend/ # Bun HTTP + WebSocket API, serves SPA in production
frontend/ # Vite SPA (search, torrents, settings)
packages/
rutracker-ts/ # RuTracker client (login, search, CF bypass)
typescript-config/ # Shared TypeScript configs
docker/ # Compose files for infra (+ full stack)
- Bun
>= 1.4 - Docker (Postgres, MinIO, Byparr)
- A qBittorrent instance with Web UI / API enabled (optional but needed for the Torrents page)
bun installdocker compose -f docker/docker-compose.dev.yml up -dThis starts:
| Service | Port |
|---|---|
| Postgres | 5432 |
| MinIO | 9000 (API), 9001 (console) |
| Byparr | 8191 |
Copy examples and adjust if needed:
cp apps/backend/.env.example apps/backend/.env
cp apps/frontend/.env.example apps/frontend/.env.localDefaults match the compose file (local Postgres / MinIO / Byparr).
bun run dev- Frontend: http://localhost:3100
- Backend (tRPC): http://localhost:3101/trpc
Open Settings in the UI and configure RuTracker + qBittorrent, then use Test before searching.
Database migrations run automatically when the backend starts.
Build and run the full stack (app + Postgres + MinIO + Byparr):
docker compose -f docker/docker-compose.yml up --buildCompose uses demo credentials (brotracker / minioadmin). Change them before any networked deployment.
| Variable | Default | Description |
|---|---|---|
DATABASE_URL |
postgresql://brotracker:brotracker@localhost:5432/brotracker |
Postgres connection |
PORT |
3101 |
HTTP / WS port |
CORS_ORIGIN |
http://localhost:3100 |
Allowed browser origin |
S3_ENDPOINT |
http://localhost:9000 |
MinIO / S3 endpoint |
S3_ACCESS_KEY |
minioadmin |
S3 access key |
S3_SECRET_KEY |
minioadmin |
S3 secret key |
S3_BUCKET |
brotracker |
Cover bucket |
BYPARR_URL |
http://localhost:8191/v1 |
Cloudflare solver API |
STATIC_DIR |
(unset) | SPA assets dir (set in Docker) |
BETTER_AUTH_URL |
http://localhost:3101 |
Public backend URL for auth callbacks |
OIDC_CLIENT_ID |
(optional) | When set, enables generic OIDC; when unset, local email/password |
OIDC_CLIENT_SECRET |
(optional) | Required together with OIDC_CLIENT_ID |
OIDC_DISCOVERY_URL |
(required with OIDC) | OpenID Connect discovery URL (…/.well-known/openid-configuration) |
RuTracker and qBittorrent credentials are stored in the database via the Settings UI, not via env. The Better Auth signing secret is auto-generated into app_settings on first boot. Example IdP setup (Authentik): docker/AUTHENTIK.md.
| Variable | Default | Description |
|---|---|---|
VITE_BACKEND_URL |
"" |
Backend host for tRPC/WS. Empty = same origin (production). Dev: http://localhost:3101 |
GitHub Actions (.github/workflows/ci.yml):
| Event | What runs |
|---|---|
PR / push to main |
Unit tests + Docker image build (no push) |
Tag v* (e.g. v1.0.0) |
Unit tests + build + push to Docker Hub |
Image: brofrong/brotracker (:1.0.0, :1.0, :1, :latest).
Add repository secrets:
| Secret | Value |
|---|---|
DOCKERHUB_USERNAME |
Docker Hub username |
DOCKERHUB_TOKEN |
Docker Hub access token |
Version lives in the root package.json and is baked into the frontend at build time (VITE_APP_VERSION).
Before releasing, add one markdown file per change under changes/unreleased/:
---
type: feature
---
Short description of the change.type is feature, fix, or breaking. The release script assembles these into GitHub Release notes, then archives them to changes/vX.Y.Z/.
bun run release # interactive patch/minor/major
bun run release patch # 0.1.0 → 0.1.1
bun run release minor # 0.1.0 → 0.2.0
bun run release 1.0.0 # set exact version
bun run release patch --yes # skip confirmation
bun run release patch --dry-run
bun run release patch --notes-file /path/to/draft-notes.mdThe script requires release notes (from changes/unreleased/ or --notes-file), bumps the version, commits, creates annotated tag vX.Y.Z, pushes branch + tag, creates a GitHub Release with the assembled notes, and archives note files (CI publishes the Docker image on tag push).
| Command | Description |
|---|---|
bun run dev |
Start all apps in watch mode |
bun run build |
Build all packages/apps |
bun run test |
Backend + rutracker-ts unit tests |
bun run release |
Bump version, tag, and push a release |
bun run lint |
Lint via Turbo |
bun run check-types |
Typecheck via Turbo |
Backend DB helpers (from apps/backend):
bun run db:generate
bun run db:migrate
bun run db:studio- Auth protects all tRPC procedures and WebSocket subscriptions; unauthenticated requests receive
UNAUTHORIZED. - Without OIDC: local email/password with one-time bootstrap registration (first user only).
- With OIDC: any OpenID Connect IdP — restrict who can sign in via that IdP’s policies. Local Authentik: docker/AUTHENTIK.md.
- Settings still store RuTracker / qBittorrent credentials in the database.
- Never commit
.env,.env.local,docker/authentik.env, or real OIDC client secrets. - Default Docker passwords are for local demos only.
MIT © brofrong