Getting Started

JellyGlance runs as a Vite React web app backed by an Express API and PostgreSQL. You can run it locally while developing, or use Docker Compose for the normal self-hosted setup.

Requirements

• Node.js 22 or newer
• npm 10 or newer
• PostgreSQL 16 or newer for local API development
• Docker and Docker Compose for container deployment
• A Jellyfin server URL and API key

Docker Start

docker compose up -d

Open JellyGlance at http://localhost:3000.

Before exposing it outside your LAN, update these values in docker-compose.yml:

• JWT_SECRET
• POSTGRES_PASSWORD
• TZ

Docker mounts ./config to /app/config and ./backups to /app/backups, making backup files easy to copy, archive, and restore.

Local Development

npm install
npm run dev

The API listens on http://localhost:3000. The Vite app listens on http://localhost:3001.

Copy the API environment example before starting local API development:

cp apps/api/.env.example apps/api/.env

Then fill in PostgreSQL connection settings and JWT_SECRET.

First Setup

1. Open JellyGlance.
2. Enter your Jellyfin server URL.
3. Enter a Jellyfin API key so JellyGlance can validate the server and sync library data.
4. Choose your admin access mode.
5. Complete Jellyfin Quick Connect, OIDC/Auth provider details, or local admin creation.
6. Review the integrations step and connect any services you want ready from the start.
7. Optionally import older Tautulli or Jellystat watch history.
8. Let the first sync finish.

After setup, JellyGlance can use cached artwork from your Jellyfin library for the login background.

See the screenshots gallery for the current first-run screens.

What To Configure Next

Once Jellyfin is connected, the most useful follow-up configuration lives in Settings:

Settings Area	What It Controls
Integrations	Jellyfin, 3rd Party Apps, Seerr apps, Arr apps, download clients, health checks, and integration event sources
Tasks	Manual and scheduled sync jobs for Jellyfin, calendar, downloads, health checks, and backups
Webhooks	One or many webhook destinations with event toggles, test delivery, and delivery history
API Key	Scoped JellyGlance access tokens for automation, Homepage/Homarr widgets, and /api/widgets/homepage
Library Settings	Library sync behavior and manual scan options
Imports	Tautulli backup upload, preview, safe import, and manual media linking for unmatched history
Newsletter	SMTP settings, recipients, preview generation, test sends, manual digest sends, and send history
Backup	Backup export options for JellyGlance data
Logs	Task, sync, webhook, health, and audit history

New Feature Quick Wins

After the first Jellyfin sync, these areas are worth opening first:

Page	Why It Matters
Home	Reorder sections, hide noise, choose a preset, pin important widgets, switch density, tune alert rules, or open /home/kiosk for a wall display.
Settings > Integrations > 3rd Party Apps	Connect Wizarr, Tdarr, Maintainerr, or SickChill for invites, transcodes, cleanup visibility, and alternative TV automation.
Requests	Connect Jellyseerr or Overseerr to review request cards, posters, availability, requester info, status filters, and actions.
Downloads	Connect qBittorrent, Transmission, Deluge, SABnzbd, NZBGet, or rTorrent for live queues, add, pause, and remove.
Active Transcodes	Connect Tdarr to monitor active, queued, and historical transcode work with progress and media artwork.
Invites	Connect Wizarr to create, copy, open, and remove invite links inside JellyGlance.
Users	Open a profile to see favourites, Movie and Show watchlists, Continue Watching, Recently Watched, next episodes, and profile media search.
Repair	Review missing artwork, missing runtime, empty series, orphaned activity, unmatched imports, and recent task failures.
Settings > Imports	Bring old Tautulli watch history into JellyGlance and link unmatched legacy media to current Jellyfin items.
Settings > Newsletter	Build and send a JellyGlance digest with recently added media, weekly watch stats, active viewers, and repair status.
Settings > Health	Check Jellyfin, database, tasks, webhooks, integrations, and backup freshness from one compact operations view.

Integrations Quick List

JellyGlance can connect to:

• Jellyfin for media, users, sessions, activity, and artwork
• Wizarr, Tdarr, Maintainerr, and SickChill under 3rd Party Apps
• Tautulli backup files for legacy Plex watch-history imports
• Jellyseerr and Overseerr for media requests and availability checks
• Sonarr, Radarr, and Lidarr for release calendars; Bazarr and Prowlarr for automation health; SickChill for connect/health only (not calendar sync)
• qBittorrent, Transmission, Deluge, rTorrent, SABnzbd, and NZBGet for download queues and torrent/magnet submission
• Discord, Gotify, ntfy, and Telegram webhook endpoints for notifications and delivery history
• SMTP servers for manual, weekly, or monthly newsletter digest delivery

See Integrations for the complete setup map.

Common Commands

npm run lint
npm run build
npm run build:docs
npm run docs:dev

Next Steps

• Review the FAQ if first-run, sync, or a missing page is stuck.
• Review Architecture to understand the workspace.
• Review Integrations to map your media stack.
• Review the Roadmap for what is next.
• Review Docker before deploying.
• Review Unraid and TrueNAS if you are wrapping the compose stack.
• Review Releases before tagging changes.