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¶
Download the example docker-compose.yml into an empty folder, update the passwords and JWT_SECRET, then run the following command from that folder.
Open JellyGlance at http://localhost:3000.
Before exposing it outside your LAN, update these values in docker-compose.yml:
JWT_SECRETPOSTGRES_PASSWORDTZ
Docker mounts ./config to /app/config and ./backups to /app/backups, making backup files easy to copy, archive, and restore.
Local Development¶
These commands run in the JellyGlance application repository, not this documentation project. Clone that repository first.
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:
Then fill in PostgreSQL connection settings and JWT_SECRET.
First Setup¶
- Open JellyGlance.
- Enter your Jellyfin server URL.
- Enter a Jellyfin API key so JellyGlance can validate the server and sync library data.
- Choose your admin access mode.
- Complete Jellyfin Quick Connect, OIDC/Auth provider details, or local admin creation.
- Review the integrations step and connect any services you want ready from the start.
- Optionally import older Tautulli or Jellystat watch history.
- 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, delivery history, and notification cards that can match the web UI theme or use a default card style |
| API Key | Create tokens (widgets-only, widgets-write, or full), then copy Homarr widgets or the Homepage YAML pack. The same page can try widget routes in Swagger |
| 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. Family presets surface Watch tonight from household continue watching, shared watchlists, and unfinished titles. |
| 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. The Household role lands on My Glance and does not get admin Home. Manager can manage users and requests but does not get Repair. |
| 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 house digest, or a per-user campaign that emails each opted-in Jellyfin user their continue watching, requests, and recently added. |
| 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¶
To work on this documentation site, follow Documentation setup.
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 Docker before deploying.
- Review Unraid and TrueNAS if you are wrapping the compose stack.