A self-hosted web dashboard for Plex media server administration.
WebServarr brings together your Plex streams, service health monitoring, media requests, upcoming releases, and news announcements into a single, themeable portal.

---

Features

• Live Plex Streams -- Active stream monitoring with quality indicators (direct play, transcode, resolution details)
• Service Health -- Real-time status tiles powered by Uptime Kuma with auto-fit grid and selfh.st icons
• System Gauges -- CPU, RAM, and network utilization from Netdata displayed as animated SVG gauges
• Media Requests -- Search TMDB, create requests, and track status via Seerr integration
• Issue Tracking -- Report and manage media issues (audio, video, subtitle) through Seerr
• Release Calendar -- Combined Radarr and Sonarr calendar with month navigation and homepage 7-day strip
• News System -- Publish announcements and maintenance notices with rich text and pinning
• Notifications -- In-app bell notifications and optional browser push (Web Push / VAPID) for request updates, issue responses, service changes, and news posts
• Themeable -- Full theme engine with color pickers, Google Fonts, custom CSS, logo upload, configurable sidebar labels and icons
• Ticket System -- User support tickets with categories, priority levels, image attachments, and admin management
• Three Auth Methods -- Local username/password (default), direct Plex OAuth, or Plex via Authentik OIDC (for multi-service SSO)
• Security Hardened -- Rate limiting on all endpoints, magic number upload verification, authenticated file serving, full dependency pinning

Quick Start

Option A — Docker Compose (recommended)

# 1. Download the compose file
curl -O https://raw.githubusercontent.com/JordanFromIT/webservarr/main/docker-compose.yml

# 2. Start the container
docker compose up -d

# 3. Open the dashboard
open http://localhost:7979

Option B — docker run

docker run -d \
  --name webservarr \
  --restart unless-stopped \
  -p 7979:7979 \
  -v ./data:/app/data \
  -v ./uploads:/app/app/static/uploads \
  ghcr.io/jordanfromit/webservarr:latest

On first launch, a setup wizard will guide you through creating an admin account, generating a secret key, and optionally connecting Plex. After setup, head to Settings to configure your other integrations.

HTTPS: WebServarr does not handle HTTPS directly. We strongly recommend placing it behind a reverse proxy for TLS termination. Cloudflare Tunnel is free and requires no port forwarding or certificates. See docs/setup.md for details.

Configuration

All configuration is done through the Settings UI after logging in. No .env file is required for basic operation.

Integrations

Navigate to Settings > Integrations to connect your services:

Integration	What You Need	What It Provides
Plex	Server URL + API token	Active streams, quality monitoring, Plex OAuth login
Uptime Kuma	URL + status page slug	Service health tiles on the homepage
Seerr	URL + API key	Media requests, issue tracking, TMDB search, login backgrounds
Radarr	URL + API key	Upcoming movie releases on calendar
Sonarr	URL + API key	Upcoming TV episode releases on calendar
Netdata	URL	CPU, RAM, and network gauges on the homepage

Each integration has a Test Connection button to verify your credentials before saving.

Authentication

WebServarr supports three authentication methods, configurable in Settings > System > Authentication:

1. Local Auth (default) -- Username and password login against the local database. Enabled out of the box. Can be disabled once another auth method is configured.

2. Direct Plex OAuth -- Users sign in with their Plex account. Same PIN-based flow used by Seerr and Tautulli. Enable in Settings > System > Authentication after configuring Plex integration.

3. Authentik OIDC -- Plex login through an Authentik identity provider. Best for admins who run multiple services and want centralized SSO. See docs/authentik.md for setup instructions.

Environment Variables

For most users, the Settings UI is sufficient. Advanced users can override defaults via environment variables:

Variable	Default	Description
APP_DOMAIN	localhost	Your domain — used for CSP headers (e.g., dashboard.example.com)
APP_SCHEME	https	URL scheme — used for CSP headers (http for local development)
REDIS_URL	redis://localhost:6379/0	Redis connection string (embedded; override to use external Redis)
CORS_ORIGINS	""	Additional CORS origins (comma-separated)
CSP_FRAME_SRC	""	Additional CSP frame-src origins
CSP_CONNECT_SRC	""	Additional CSP connect-src origins

Tech Stack

• Backend: FastAPI (Python 3.11), SQLite, Redis sessions
• Frontend: Vanilla JavaScript, Tailwind CSS (CDN), Material Design Icons
• Deployment: Docker Compose (single container with embedded Redis)

Project Structure

app/
  main.py              # FastAPI app entry point
  config.py            # Settings from environment variables
  models.py            # SQLAlchemy ORM models
  seed.py              # Default settings seeded on first startup
  auth.py              # Session manager + OIDC client
  routers/             # API route handlers
  integrations/        # External service API clients (Plex, Seerr, etc.)
  services/            # Background services (notification poller, push dispatch)
  static/              # Frontend HTML/JS/CSS pages
docs/
  setup.md             # Installation and operations guide

Updating

docker compose pull
docker compose up -d

Data is stored in ./data/ (SQLite database) and ./uploads/ (logos). These directories persist across updates.

Backup

Back up these directories regularly:

• data/ -- SQLite database (users, news, settings, notifications)
• uploads/ -- Uploaded assets (logos)
• .env -- Environment overrides (if you use any)

Documentation

• docs/setup.md -- Full installation and operations guide

Contributing

Contributions are welcome. Please open an issue to discuss significant changes before submitting a pull request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes
4. Push to your fork and open a pull request

License

GPL-3.0