icmppp/jellytics repository overview

     ██╗███████╗██╗     ██╗  ██╗   ██╗████████╗██╗ ██████╗███████╗
     ██║██╔════╝██║     ██║  ╚██╗ ██╔╝╚══██╔══╝██║██╔════╝██╔════╝
     ██║█████╗  ██║     ██║   ╚████╔╝    ██║   ██║██║     ███████╗
██   ██║██╔══╝  ██║     ██║    ╚██╔╝     ██║   ██║██║     ╚════██║
╚█████╔╝███████╗███████╗███████╗██║      ██║   ██║╚██████╗███████║
 ╚════╝ ╚══════╝╚══════╝╚══════╝╚═╝      ╚═╝   ╚═╝ ╚═════╝╚══════╝

⁠✨ Features

🗓️ Watch Statistics: Daily snapshots of your viewing habits broken down by genre, time, and content type. See exactly how much of your life you've given to television.

📜 Full Watch History: Every single thing you've ever watched, timestamped and searchable. No more "wait, did I already watch that?"

⭐ Ratings & Reviews: Score anything out of 10 and write personal notes or a full review. Your opinions, stored forever.

🔖 Watchlist: Save what you want to watch next. Never lose a recommendation again.

🗂️ Custom Collections: Group your media however your brain works, by franchise, director, mood, genre, or anything else.

🏷️ Tags: Create your own colored labels and slap them on anything. Your library, your rules.

🤖 Recommendations: Personalized suggestions based on what you actually watch, not what an algorithm thinks you should.

📡 Live Sessions: See what's playing right now across every screen in your home, in real time.

👨‍👩‍👧‍👦 Multi-User: Every Jellyfin account in your household gets their own private profile, stats, watchlist, and preferences. Completely separate.

📦 Archive: Done with a series forever? Archive it to keep things tidy without losing any data.

🔔 Notifications: In-app alerts for sync events and household activity.

⁠🚀 Getting Started

You need two things:

• 🐳 Docker + Docker Compose v2+ on your server
• 📺 A running Jellyfin server on your network

⁠1️⃣ Create your compose file

Drop this into a new file called docker-compose.yml:

services:
  jellytics:
    image: icmppp/jellytics:latest
    container_name: jellytics
    restart: unless-stopped
    ports:
      - "80:3000"
    volumes:
      - jellytics-data:/app/data
    environment:
      - JELLYTICS_DATABASE_PATH=/app/data/jellytics.db
      # 👇 Keeps sessions alive across restarts. Generate with: openssl rand -base64 32
      # - JWT_SECRET=your_secret_here

volumes:
  jellytics-data:

⁠2️⃣ Fire it up

docker compose up -d

⁠3️⃣ Open it up

Head to http://your-server-ip⁠ in your browser. A quick setup wizard will walk you through connecting your Jellyfin server. Just enter your Jellyfin URL, username, and password. Done. Your library starts syncing automatically. 🎉

⁠⚙️ Configuration

Most people won't need to touch a thing. But here's what's worth knowing about:

⁠🔌 Change the port

Jellytics uses port 80 by default. Change the left number to whatever you want:

ports:
  - "8096:3000"   # → now at http://your-server:8096

⁠🔐 Keep sessions alive across restarts

Without this set, everyone gets logged out whenever the container restarts. Generate a secret once:

openssl rand -base64 32

Then add it to environment in your compose file:

- JWT_SECRET=paste_your_generated_secret_here

⁠🔄 Control how often the library syncs

- JELLYTICS_SYNC_INTERVAL_SECONDS=300   # every 5 minutes (this is the default)

⁠🔒 Localhost-only mode

Running a reverse proxy in front? Lock Jellytics to local access only:

ports:
  - "127.0.0.1:3000:3000"

⁠🌐 Putting it behind a domain

Want to access Jellytics at jellytics.yourdomain.com? Point your reverse proxy at port 3000.

server {
    listen 80;
    server_name jellytics.yourdomain.com;

    location / {
        proxy_pass         http://127.0.0.1:3000;
        proxy_set_header   Host               $host;
        proxy_set_header   X-Real-IP          $remote_addr;
        proxy_set_header   X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto  $scheme;
    }
}

jellytics.yourdomain.com {
    reverse_proxy localhost:3000
}

labels:
  - "traefik.http.routers.jellytics.rule=Host(`jellytics.yourdomain.com`)"
  - "traefik.http.services.jellytics.loadbalancer.server.port=3000"

⁠💾 Backing up your data

All of your stats, reviews, ratings, and watchlists live in a Docker volume called jellytics-data. Back it up. You'll thank yourself later.

Back up:

docker cp jellytics:/app/data ./jellytics-backup

Restore:

docker cp ./jellytics-backup jellytics:/app/data
docker compose restart

⁠🔁 Updating

docker compose pull && docker compose up -d

Your data stays exactly where it is. Migrations run automatically. ✅

⁠🛠️ Troubleshooting

docker compose logs -f

docker compose restart

docker compose ps

docker compose down -v
docker compose up -d

⁠🔨 Building from source

Prefer to build it yourself? No problem:

git clone https://github.com/icmpp/jellytics.git
cd jellytics
docker compose up -d --build

⁠🤝 Contributing

Got a bug to report or a feature idea? Open an issue⁠ on GitHub. Contributions are very welcome.