Add Jellyfin tier 1 features: Intro Skipper, TMDb Box Sets, Jellystat

- Jellystat analytics container (postgres + app) behind jellyfin profile
- Auto-install Intro Skipper and TMDb Box Sets plugins via configure.sh
- Setup.sh generates Jellystat JWT secret and DB password
- Health check and auto-healer cover Jellystat containers
- Updated README with Jellyfin-specific features section
- Updated SETUP.md with plugin and Jellystat setup steps

Author: liamvibecodes

.env.example

@@ -34,6 +34,10 @@ WIREGUARD_ADDRESSES=your_wireguard_address_here
 UN_SONARR_0_API_KEY=your_sonarr_api_key_here
 UN_RADARR_0_API_KEY=your_radarr_api_key_here
 
+# --- JELLYSTAT (Jellyfin analytics, auto-generated by setup.sh) ---
+JELLYSTAT_JWT_SECRET=
+JELLYSTAT_DB_PASSWORD=
+
 # --- OPTIONAL: MUSIC (Lidarr + Tidarr) ---
 # Uncomment if using music services (bash scripts/setup-music.sh)
 # UN_LIDARR_0_API_KEY=your_lidarr_api_key_here

README.md

@@ -52,6 +52,9 @@ New to self-hosted media? Start with the [basic version](https://github.com/liam
 | **Kometa** | Plex metadata automation (franchise collections, resolution overlays, RT ratings) |
 | **Unpackerr** | Auto-extracts RAR'd downloads for Radarr/Sonarr |
 | **Jellyfin** | Free, open-source media server (alternative to Plex, runs in Docker) |
+| **Intro Skipper** | Jellyfin plugin: auto-detects intros and adds a "Skip Intro" button on TV shows |
+| **TMDb Box Sets** | Jellyfin plugin: auto-creates franchise collections from TMDb data (Jellyfin's Kometa) |
+| **Jellystat** | Jellyfin analytics dashboard (like Tautulli for Plex: watch history, user stats, library insights) |
 
 ## Choosing Your Media Server
 
@@ -61,11 +64,36 @@ New to self-hosted media? Start with the [basic version](https://github.com/liam
 | **Setup** | Install macOS app, runs natively | Runs in Docker, no app install |
 | **Remote access** | Built-in (Plex account) | Manual (reverse proxy) |
 | **Kometa support** | Yes (metadata automation) | No (use Jellyfin's built-in collections) |
-| **Franchise sort** | Yes (via franchise-sort.py) | No (use Jellyfin Collections plugin) |
+| **Franchise sort** | Yes (via franchise-sort.py) | No (TMDb Box Sets plugin auto-creates collections) |
+| **Analytics** | Tautulli (external) | Jellystat (included, Docker) |
+| **Intro skip** | Plex Pass feature | Intro Skipper plugin (free, auto-installed) |
 | **Client apps** | Plex apps on all platforms | Jellyfin apps + browser |
 
 Default is **Plex**. To use Jellyfin, pass `--jellyfin` to the bootstrap command.
 
+## Jellyfin-Specific Features
+
+When running with `MEDIA_SERVER=jellyfin`, the stack includes these extras that close the gap with Plex Pass users:
+
+| Feature | What It Does | Plex Equivalent |
+|---------|-------------|-----------------|
+| **Intro Skipper** | Detects TV show intros via audio fingerprinting, adds a "Skip Intro" button | Plex Pass intro skip |
+| **TMDb Box Sets** | Auto-creates franchise collections (Marvel, Star Wars, etc.) from TMDb data | Kometa collections |
+| **Jellystat** | Watch history, user activity, library stats dashboard at `http://localhost:3000` | Tautulli |
+
+Intro Skipper and TMDb Box Sets are auto-installed as Jellyfin plugins by `configure.sh`. Jellystat runs as a separate Docker service behind the `jellyfin` profile.
+
+### Jellystat Setup
+
+After the stack is running:
+
+1. Open `http://localhost:3000`
+2. Create an admin account
+3. Connect to your Jellyfin server: `http://jellyfin:8096`
+4. Enter your Jellyfin API key (Administration > API Keys)
+
+Jellystat will start tracking watch history, user activity, and library statistics automatically.
+
 ## Optional: Music (Lidarr + Tidarr)
 
 | Service | What It Does |
@@ -86,7 +114,7 @@ Then open Tidarr at `http://localhost:8484` to authenticate with your Tidal acco
 
 | Script | Schedule | What It Does |
 |--------|----------|-------------|
-| Auto-healer | Hourly | Restarts VPN/containers if they go down (includes Jellyfin when active) |
+| Auto-healer | Hourly | Restarts VPN/containers if they go down (includes Jellyfin + Jellystat when active) |
 | Nightly backup | Daily | Backs up all configs and databases (14-day retention) |
 | Download watchdog | Every 15 min | Detects stalled/slow torrents, auto-fixes or swaps them |
 | Kometa | Every 4 hours | Updates Plex collections and metadata overlays |

SETUP.md

@@ -198,7 +198,11 @@ It also writes credentials/API keys to `<MEDIA_DIR>/state/first-run-credentials.
 1. Open http://localhost:8096
 2. Complete the setup wizard
 3. Add libraries: Movies = `/data/movies`, TV Shows = `/data/tvshows`
-4. Generate an API key (Administration > API Keys) if you plan to use `archive-media.sh --only-watched`
+4. Generate an API key (Administration > API Keys) for Jellystat and `archive-media.sh --only-watched`
+
+**Plugins:** `configure.sh` auto-installs **Intro Skipper** (adds "Skip Intro" button on TV shows) and **TMDb Box Sets** (auto-creates franchise collections). A Jellyfin restart is required after plugin install. If auto-install fails, install them manually via Administration > Plugins > Catalog.
+
+**Jellystat** (analytics): Open `http://localhost:3000`, create an account, and connect to `http://jellyfin:8096` with your API key. Tracks watch history, user activity, and library stats.
 
 ---
 
@@ -286,6 +290,7 @@ bash scripts/vpn-mode.sh status
 | Browse and request | http://localhost:5055 |
 | Watch (Plex) | http://localhost:32400/web |
 | Watch (Jellyfin) | http://localhost:8096 |
+| Jellyfin analytics (Jellystat) | http://localhost:3000 |
 | Check downloads | http://localhost:8080 |
 | Transcode status | http://localhost:8265 |
 

docker-compose.yml

@@ -247,6 +247,43 @@ services:
       retries: 3
     restart: unless-stopped
 
+  jellystat-db:
+    image: postgres:18.1
+    container_name: jellystat-db
+    profiles: ["jellyfin"]
+    environment:
+      - POSTGRES_DB=jfstat
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=${JELLYSTAT_DB_PASSWORD}
+    volumes:
+      - ${MEDIA_DIR}/config/jellystat/db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    restart: unless-stopped
+
+  jellystat:
+    image: cyfershepard/jellystat:latest
+    container_name: jellystat
+    profiles: ["jellyfin"]
+    depends_on:
+      jellystat-db:
+        condition: service_healthy
+    environment:
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=${JELLYSTAT_DB_PASSWORD}
+      - POSTGRES_IP=jellystat-db
+      - POSTGRES_PORT=5432
+      - JWT_SECRET=${JELLYSTAT_JWT_SECRET}
+      - TZ=${TIMEZONE:-America/New_York}
+    volumes:
+      - ${MEDIA_DIR}/config/jellystat/backup:/app/backend/backup-data
+    ports:
+      - 127.0.0.1:3000:3000
+    restart: unless-stopped
+
   # ─── Optional: Music (Lidarr + Tidarr) ───
   # Uncomment to add music management. Run: bash scripts/setup-music.sh first.
 

scripts/auto-heal.sh

@@ -61,7 +61,7 @@ source "$PROJECT_DIR/.env" 2>/dev/null || true
 # Check containers
 CONTAINERS="gluetun qbittorrent prowlarr sonarr radarr bazarr flaresolverr seerr tdarr unpackerr recyclarr lidarr tidarr"
 if [[ "${MEDIA_SERVER:-plex}" == "jellyfin" ]]; then
-    CONTAINERS="$CONTAINERS jellyfin"
+    CONTAINERS="$CONTAINERS jellyfin jellystat-db jellystat"
 fi
 for name in $CONTAINERS; do
     state=$(docker inspect -f '{{.State.Status}}' "$name" 2>/dev/null)

scripts/configure.sh

@@ -407,6 +407,99 @@ fi
 
 echo ""
 
+# 7. Jellyfin plugins (Intro Skipper + TMDb Box Sets)
+if [[ "$MEDIA_SERVER" == "jellyfin" ]]; then
+    echo -e "${CYAN}[*] Installing Jellyfin plugins...${NC}"
+    echo ""
+
+    # Wait for Jellyfin API
+    JF_READY=false
+    for i in $(seq 1 30); do
+        jf_status=$(curl -s -o /dev/null -w "%{http_code}" --max-time 3 "http://localhost:8096/health" 2>/dev/null || true)
+        if [[ "$jf_status" == "200" ]]; then
+            JF_READY=true
+            break
+        fi
+        sleep 2
+    done
+
+    if [[ "$JF_READY" == true ]]; then
+        # Extract API key from Jellyfin system.xml
+        JF_XML="$MEDIA_DIR/config/jellyfin/config/system.xml"
+        JF_API_KEY=""
+        if [[ -f "$JF_XML" ]]; then
+            JF_API_KEY=$(grep -o '<ApiKey>[^<]*</ApiKey>' "$JF_XML" 2>/dev/null | sed 's/<[^>]*>//g' || true)
+        fi
+
+        if [[ -z "$JF_API_KEY" ]]; then
+            warn "Could not extract Jellyfin API key from system.xml"
+            warn "Generate one in Jellyfin > Administration > API Keys, then install plugins manually:"
+            warn "  - Intro Skipper: Administration > Plugins > Catalog > Intro Skipper > Install"
+            warn "  - TMDb Box Sets: Administration > Plugins > Catalog > TMDb Box Sets > Install"
+        else
+            # Fetch plugin catalog
+            PLUGIN_CATALOG=$(curl -fsS "http://localhost:8096/Packages" -H "X-Emby-Token: $JF_API_KEY" 2>/dev/null || true)
+
+            install_jf_plugin() {
+                local plugin_name="$1"
+                if [[ -z "$PLUGIN_CATALOG" ]]; then
+                    warn "$plugin_name: could not fetch plugin catalog"
+                    return 0
+                fi
+
+                # Extract the plugin GUID from catalog
+                local plugin_guid
+                plugin_guid=$(echo "$PLUGIN_CATALOG" | grep -o "\"name\":\"$plugin_name\"[^}]*\"guid\":\"[^\"]*\"" | grep -o '"guid":"[^"]*"' | cut -d'"' -f4 || true)
+
+                if [[ -z "$plugin_guid" ]]; then
+                    warn "$plugin_name: not found in plugin catalog"
+                    warn "  Install manually: Administration > Plugins > Catalog > $plugin_name"
+                    return 0
+                fi
+
+                # Get latest version
+                local install_result
+                install_result=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
+                    "http://localhost:8096/Packages/Installed/$plugin_name" \
+                    -H "X-Emby-Token: $JF_API_KEY" 2>/dev/null || echo "000")
+
+                if [[ "$install_result" =~ ^2 ]]; then
+                    log "$plugin_name plugin installed"
+                else
+                    warn "$plugin_name: install returned HTTP $install_result"
+                    warn "  Install manually: Administration > Plugins > Catalog > $plugin_name"
+                fi
+            }
+
+            install_jf_plugin "Intro Skipper"
+            install_jf_plugin "TMDb Box Sets"
+
+            echo ""
+            if [[ "$NON_INTERACTIVE" == true ]]; then
+                warn "Restart Jellyfin to activate plugins: docker compose restart jellyfin"
+            else
+                echo -e "  ${YELLOW}Plugins require a Jellyfin restart to activate.${NC}"
+                read -p "  Restart Jellyfin now? [Y/n] " -r restart_jf
+                if [[ "$restart_jf" =~ ^[Nn]$ ]]; then
+                    warn "Skipped. Run 'docker compose restart jellyfin' when ready."
+                else
+                    if docker compose restart jellyfin >/dev/null 2>&1; then
+                        log "Jellyfin restarted"
+                    else
+                        warn "Restart failed. Run 'docker compose restart jellyfin' manually."
+                    fi
+                fi
+            fi
+        fi
+    else
+        warn "Jellyfin not ready after 60 seconds. Skipping plugin install."
+        warn "Install manually after Jellyfin is running:"
+        warn "  - Intro Skipper: Administration > Plugins > Catalog > Intro Skipper > Install"
+        warn "  - TMDb Box Sets: Administration > Plugins > Catalog > TMDb Box Sets > Install"
+    fi
+    echo ""
+fi
+
 # Print API keys for user to update config templates
 echo "=============================="
 echo -e "  ${GREEN}Configuration complete!${NC}"

scripts/health-check.sh

@@ -51,7 +51,7 @@ echo ""
 echo "Containers:"
 CONTAINER_LIST="gluetun qbittorrent prowlarr sonarr radarr bazarr flaresolverr seerr tdarr unpackerr recyclarr kometa tautulli lidarr tidarr"
 if [[ "$MEDIA_SERVER" == "jellyfin" ]]; then
-    CONTAINER_LIST="$CONTAINER_LIST jellyfin"
+    CONTAINER_LIST="$CONTAINER_LIST jellyfin jellystat-db jellystat"
 fi
 for name in $CONTAINER_LIST; do
     state=$(docker inspect -f '{{.State.Status}}' "$name" 2>/dev/null)
@@ -65,6 +65,8 @@ for name in $CONTAINER_LIST; do
         echo -e "  ${YELLOW}SKIP${NC}  $name (not installed)"
     elif [[ "$name" == "lidarr" || "$name" == "tidarr" ]] && [[ -z "$state" ]]; then
         echo -e "  ${YELLOW}SKIP${NC}  $name (music profile not enabled)"
+    elif [[ "$name" == "jellystat-db" || "$name" == "jellystat" ]] && [[ -z "$state" ]]; then
+        echo -e "  ${YELLOW}SKIP${NC}  $name (jellyfin profile not enabled)"
     else
         echo -e "  ${RED}FAIL${NC}  $name (${state:-not found})"
         ((FAIL++))
@@ -124,6 +126,37 @@ echo ""
 if [[ "$MEDIA_SERVER" == "jellyfin" ]]; then
     echo "Jellyfin:"
     check_service "Jellyfin" "http://localhost:8096/health"
+
+    # Jellystat (only if containers exist)
+    jellystat_state=$(docker inspect -f '{{.State.Status}}' jellystat 2>/dev/null || true)
+    if [[ -n "$jellystat_state" ]]; then
+        echo ""
+        echo "Jellystat:"
+        if [[ "$jellystat_state" == "running" ]]; then
+            jellystat_http=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "http://localhost:3000" 2>/dev/null)
+            if [[ "$jellystat_http" =~ ^[23][0-9][0-9]$ ]]; then
+                echo -e "  ${GREEN}OK${NC}  Jellystat"
+                ((PASS++))
+            else
+                echo -e "  ${RED}FAIL${NC}  Jellystat (HTTP $jellystat_http)"
+                ((FAIL++))
+            fi
+        else
+            echo -e "  ${RED}FAIL${NC}  Jellystat ($jellystat_state)"
+            ((FAIL++))
+        fi
+
+        jellystat_db_health=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}unknown{{end}}' jellystat-db 2>/dev/null || true)
+        if [[ "$jellystat_db_health" == "healthy" ]]; then
+            echo -e "  ${GREEN}OK${NC}  Jellystat DB"
+            ((PASS++))
+        elif [[ -z "$jellystat_db_health" ]]; then
+            echo -e "  ${YELLOW}SKIP${NC}  Jellystat DB (not found)"
+        else
+            echo -e "  ${RED}FAIL${NC}  Jellystat DB (health: $jellystat_db_health)"
+            ((FAIL++))
+        fi
+    fi
 else
     echo "Plex:"
     plex_status=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "http://localhost:32400/web" 2>/dev/null)

scripts/setup.sh

@@ -69,17 +69,44 @@ echo "Creating folders..."
 mkdir -p "$MEDIA_DIR"/{config,Downloads,Movies,"TV Shows",logs,state,backups,tdarr-transcode-cache}
 mkdir -p "$MEDIA_DIR"/config/{qbittorrent,prowlarr,sonarr,radarr,bazarr,seerr,kometa,recyclarr}
 mkdir -p "$MEDIA_DIR"/config/tdarr/{server,configs,logs}
+mkdir -p "$MEDIA_DIR"/config/jellystat/{db,backup}
 echo -e "  ${GREEN}Done${NC}"
 echo ""
 
 # Create .env from example
+# Generate Jellystat secrets if not already set
+if [[ -f "$SCRIPT_DIR/.env" ]]; then
+    source "$SCRIPT_DIR/.env"
+fi
+if [[ -z "${JELLYSTAT_JWT_SECRET:-}" ]]; then
+    JELLYSTAT_JWT_SECRET=$(openssl rand -hex 32)
+    echo "  Generated JELLYSTAT_JWT_SECRET"
+fi
+if [[ -z "${JELLYSTAT_DB_PASSWORD:-}" ]]; then
+    JELLYSTAT_DB_PASSWORD=$(openssl rand -hex 16)
+    echo "  Generated JELLYSTAT_DB_PASSWORD"
+fi
+
 if [[ -f "$SCRIPT_DIR/.env" ]]; then
     echo -e "${YELLOW}Note:${NC} .env already exists. Skipping creation."
+    # Write Jellystat secrets if missing from existing .env
+    if ! grep -q "^JELLYSTAT_JWT_SECRET=" "$SCRIPT_DIR/.env" 2>/dev/null; then
+        printf '\nJELLYSTAT_JWT_SECRET=%s\n' "$JELLYSTAT_JWT_SECRET" >> "$SCRIPT_DIR/.env"
+    elif grep -q "^JELLYSTAT_JWT_SECRET=$" "$SCRIPT_DIR/.env" 2>/dev/null; then
+        sed -i '' "s|^JELLYSTAT_JWT_SECRET=$|JELLYSTAT_JWT_SECRET=$JELLYSTAT_JWT_SECRET|" "$SCRIPT_DIR/.env"
+    fi
+    if ! grep -q "^JELLYSTAT_DB_PASSWORD=" "$SCRIPT_DIR/.env" 2>/dev/null; then
+        printf 'JELLYSTAT_DB_PASSWORD=%s\n' "$JELLYSTAT_DB_PASSWORD" >> "$SCRIPT_DIR/.env"
+    elif grep -q "^JELLYSTAT_DB_PASSWORD=$" "$SCRIPT_DIR/.env" 2>/dev/null; then
+        sed -i '' "s|^JELLYSTAT_DB_PASSWORD=$|JELLYSTAT_DB_PASSWORD=$JELLYSTAT_DB_PASSWORD|" "$SCRIPT_DIR/.env"
+    fi
 else
     echo "Creating .env file..."
     sed "s|/Users/YOURUSERNAME/Media|$MEDIA_DIR|g" "$SCRIPT_DIR/.env.example" \
         | sed "s|PUID=501|PUID=$USER_PUID|g" \
         | sed "s|PGID=20|PGID=$USER_PGID|g" \
+        | sed "s|^JELLYSTAT_JWT_SECRET=$|JELLYSTAT_JWT_SECRET=$JELLYSTAT_JWT_SECRET|g" \
+        | sed "s|^JELLYSTAT_DB_PASSWORD=$|JELLYSTAT_DB_PASSWORD=$JELLYSTAT_DB_PASSWORD|g" \
         > "$SCRIPT_DIR/.env"
     chmod 600 "$SCRIPT_DIR/.env"
     echo -e "  ${GREEN}Done${NC}"