Development Setup
For contributors and anyone running kbarr from source.
Prerequisites
- Docker and Docker Compose
- Go (see
go.modfor the required version) - Node.js (LTS)
- air — live reload for Go services
- overmind — process manager for local dev
Setup
Clone the repository:
git clone https://github.com/kingbenny101/kbarr.git
cd kbarr
dev.env is included with sensible defaults. No changes are needed to get started.
Start all services via overmind:
make dev
This launches all services (from the Procfile) with each in its own process:
| Window | What runs |
|---|---|
db | PostgreSQL + pgAdmin |
core | Main API + frontend |
metadata | AniDB metadata service |
indexer | Torrent search service |
downloader | Download queue service |
All Go services hot-reload on file changes via air. The frontend uses Vite's dev server.
To stop everything:
make dev-down
Running individual services
Start only the database:
make db # start
make db-down # stop
Run a specific service manually:
make run-core
make run-metadata
make run-indexer
make run-downloader
make run-frontend
pgAdmin is available at http://localhost:5050 — email: admin@local.dev, password: admin.
Tech stack
| Layer | Technology |
|---|---|
| Backend services | Go |
| Frontend | React, TypeScript, Mantine |
| Database | PostgreSQL (via bun ORM) |
| API | huma v2 (OpenAPI 3.0) |
| Metadata | AniDB UDP/HTTP API |
| Torrent search | kbdex and Prowlarr (additional indexers can be wired in) |
| Download client | qBittorrent (additional clients can be wired in) |
Generating the API spec
The OpenAPI spec is generated from the running server:
go run ./cmd/genspec
To regenerate the docs API pages after updating the spec:
npm run gen-api-docs # from the docs/ directory