Skip to content

docker 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.

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

These commands run in the JellyGlance application repository, not this documentation project. Clone that repository first.

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. Choose Auto-detect, Jellyfin, or Emby, then enter the server URL.
  3. Enter that server's API key so JellyGlance can validate the server and sync library data.
  4. Choose your admin access mode.
  5. Complete Jellyfin Quick Connect, Emby username and password, OIDC, or local admin creation.
  6. Review the integrations step and connect any services you want ready from the start.
  7. Optionally import Tautulli, Jellystat, or Trakt watch history, or sync play state from the media server.
  8. Let the first sync finish.

After setup, JellyGlance can use cached artwork from the media server library for the login background.

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

What To Configure Next

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

Settings Area What It Controls
Integrations Media server (Jellyfin or Emby), 3rd Party Apps, Seerr apps, Arr apps, download clients, health checks, and integration event sources
Tasks Manual and scheduled sync jobs for the media server, 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 and Jellystat backups, Trakt accounts, and play-state sync from the connected media server
Status page A public /status page with uptime, streams, and maintenance, built under Settings → Status page
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, Audiobookshelf, or the companion health checks for invites, transcodes, cleanup, and audiobooks.
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 or Emby for media, users, sessions, activity, and artwork
  • Wizarr, Tdarr, Maintainerr, Audiobookshelf, Unpackerr, Kometa, Notifiarr, Recyclarr, and autobrr under 3rd Party Apps
  • Tautulli and Jellystat backup files, Trakt accounts, and media-server play state for watch history
  • Jellyseerr and Overseerr for media requests and availability checks
  • Sonarr, Radarr, Lidarr, and Readarr for release calendars; Bazarr and Prowlarr for automation health; SickChill for TV health only (not calendar sync)
  • qBittorrent, Transmission, Deluge, rTorrent, SABnzbd, and NZBGet for download queues and torrent or NZB submission
  • Discord, Gotify, ntfy, Telegram, and Pushover webhook endpoints for notifications and delivery history
  • SMTP for manual, weekly, or monthly newsletter digest delivery

See Integrations for the complete setup map.

Common Commands

npm run lint
npm run build

Next Steps