Helprr

Entire site was built using Claude code with Opus and Gemini. Using it daily, I haven’t found any issues in functionality so far, but I’ll update the README if I come across any bugs that I’m unable to fix. The UI is mobile-first, as I needed an Iphone app to control radarr, sonarr and qbittorrent with push notifications. I have only added features which I wanted to use myself to use from mobile, not all the options and features present in arr stack and qbittorrent is added.

Helprr is a self-hosted web dashboard (PWA) that connects to Sonarr, Radarr, and qBittorrent. It polls those services on an interval and can send Web Push notifications for common events (downloads starting/completing/failing, health warnings, upcoming releases, etc.).

📱 App Screenshots

Features

• Password-protected UI (single shared app password)
• Connect/configure Sonarr, Radarr, qBittorrent from Settings
• Dashboard + Activity feed + Calendar views
• Notifications inbox + per-device notification preferences
• PWA service worker (Serwist in production; lightweight push-only worker in development)

Tech stack

• Next.js (App Router) on port 3050
• Prisma + PostgreSQL
• Web Push (web-push) with VAPID keys

Prerequisites

• Node.js 20+
• PostgreSQL 16+ (or Docker)
• Redis 7+ (or Docker)

Environment variables

Copy .env.example to .env.local (for local dev), or set these in your deployment environment:

Variable	Required	Purpose
DATABASE_URL	yes	PostgreSQL connection string used by Prisma
REDIS_URL	yes	Redis connection string used for login rate limiting
APP_PASSWORD	yes	Password used on the /login screen
JWT_SECRET	recommended	Signs the auth cookie (set this in production)
NEXT_PUBLIC_VAPID_PUBLIC_KEY	optional	Public VAPID key (enables push notifications; must be available at build time for Docker builds)
VAPID_PRIVATE_KEY	optional	Private VAPID key (server-side)
VAPID_SUBJECT	optional	VAPID subject, e.g. mailto:you@example.com
TZ	optional	Timezone for displaying dates/times (defaults to UTC)

If VAPID vars are not set, Helprr will still run, but push notifications are disabled.

Local development

1. Install dependencies

npm ci

2. Start PostgreSQL and Redis (example using docker-compose)

docker compose up -d helprr-db helprr-redis

3. Configure .env.local

Example (adjust credentials/host to match your Postgres setup):

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/helprr
REDIS_URL=redis://localhost:6379

APP_PASSWORD=change-me
JWT_SECRET=change-me-too
TZ=Asia/Kolkata

# Optional: enable push notifications
VAPID_SUBJECT=mailto:you@example.com
NEXT_PUBLIC_VAPID_PUBLIC_KEY=...
VAPID_PRIVATE_KEY=...

4. Initialize the database schema

npm run db:generate
npm run db:push

5. Run the dev server

npm run dev

Open http://localhost:3050

Docker

The repository includes a docker-compose.yml with a Postgres container and the Helprr app.

1. Set environment variables (recommended via a local .env file that is not committed)

• POSTGRES_PASSWORD (optional override; defaults to postgres)
• DATABASE_URL (optional override; defaults to the internal compose URL)
• REDIS_URL (optional override; defaults to redis://helprr-redis:6379)
• APP_PASSWORD
• TZ (optional override; defaults to UTC)
• JWT_SECRET
• NEXT_PUBLIC_VAPID_PUBLIC_KEY (build-time)
• VAPID_PRIVATE_KEY
• VAPID_SUBJECT

2. Build and run

docker compose up --build

Notes:

• The image build expects NEXT_PUBLIC_VAPID_PUBLIC_KEY to be available as a build arg.
• The container entrypoint runs npx prisma db push --skip-generate before starting Next.js.

Generating VAPID keys (for push notifications)

You can generate a VAPID keypair with:

npx web-push generate-vapid-keys

Use the public key as NEXT_PUBLIC_VAPID_PUBLIC_KEY and the private key as VAPID_PRIVATE_KEY.

Connecting Sonarr / Radarr / qBittorrent

In the app, go to Settings and set:

• Sonarr: base URL + API key
• Radarr: base URL + API key
• qBittorrent: base URL + password (stored as the connection apiKey) + optional username (defaults to admin)

Helprr’s polling service will skip any service that is not configured.

Scripts

npm run dev
npm run build
npm run start

npm run db:generate
npm run db:push
npm run db:migrate

npm run lint

Security notes

• Set strong values for APP_PASSWORD and JWT_SECRET in production.