fix: harden jellyfin feature rollout and upgrade follow-through

Author: liamvibecodes

IMAGE_LOCK.md

@@ -23,6 +23,8 @@ Tested lock snapshot:
 | qbittorrent | `lscr.io/linuxserver/qbittorrent@sha256:065792d2b11f0facff340210fc1cf13623b029a94ecdf08b02d06d922205f618` |
 | seerr | `ghcr.io/seerr-team/seerr@sha256:1b5fc1ea825631d9d165364472663b817a4c58ef6aa1013f58d82c1570d7c866` |
 | jellyfin (optional) | `lscr.io/linuxserver/jellyfin@sha256:4ee07757abcaa0b74fbc74179392311dc2874c03b0bef04bc2d79e9e1a875793` |
+| jellystat-db (optional) | `postgres@sha256:1090bc3a8ccfb0b55f78a494d76f8d603434f7e4553543d6e807bc7bd6bbd17f` |
+| jellystat (optional) | `cyfershepard/jellystat@sha256:c8c451704ba7985340142cd047e2364cabaf41b613669b6c5340688ed217f82a` |
 | tdarr | `ghcr.io/haveagitgat/tdarr@sha256:20a5656c4af4854e1877046294f77113f949d27e35940a9a65f231423d063207` |
 | tidarr (music profile) | `cstaelen/tidarr@sha256:79a2c62aed04dbe9770272443192eae145f26bdc2d188e665b13ab763341206c` |
 

UPGRADE.md

@@ -82,9 +82,11 @@ bash scripts/health-check.sh
 
 After either upgrade path, confirm:
 
-1. `~/Media/config/kometa/config.yml` has `PLEX_TOKEN` + TMDB key
-2. Tdarr libraries/plugins are configured at `http://localhost:8265`
-3. `bash scripts/health-check.sh` reports clean results
+1. Tdarr libraries/plugins are configured at `http://localhost:8265`
+2. `bash scripts/health-check.sh` reports clean results
+3. If using Plex: `~/Media/config/kometa/config.yml` has `PLEX_TOKEN` + TMDB key
+4. If using Jellyfin: open Jellystat at `http://localhost:3000` and connect it to `http://jellyfin:8096`
+5. If using Jellyfin: restart Jellyfin once after plugin install to activate Intro Skipper/TMDb Box Sets
 
 ## Rollback
 

docker-compose.yml

@@ -248,7 +248,7 @@ services:
     restart: unless-stopped
 
   jellystat-db:
-    image: postgres:18.1
+    image: postgres@sha256:1090bc3a8ccfb0b55f78a494d76f8d603434f7e4553543d6e807bc7bd6bbd17f
     container_name: jellystat-db
     profiles: ["jellyfin"]
     environment:
@@ -265,7 +265,7 @@ services:
     restart: unless-stopped
 
   jellystat:
-    image: cyfershepard/jellystat:latest
+    image: cyfershepard/jellystat@sha256:c8c451704ba7985340142cd047e2364cabaf41b613669b6c5340688ed217f82a
     container_name: jellystat
     profiles: ["jellyfin"]
     depends_on:

scripts/configure.sh

@@ -440,33 +440,85 @@ if [[ "$MEDIA_SERVER" == "jellyfin" ]]; then
             # Fetch plugin catalog
             PLUGIN_CATALOG=$(curl -fsS "http://localhost:8096/Packages" -H "X-Emby-Token: $JF_API_KEY" 2>/dev/null || true)
 
+            url_encode() {
+                local raw="$1"
+                if command -v python3 >/dev/null 2>&1; then
+                    python3 - "$raw" <<'PY'
+import sys, urllib.parse
+print(urllib.parse.quote(sys.argv[1], safe=""))
+PY
+                else
+                    # Best-effort fallback for environments without python3
+                    printf '%s\n' "${raw// /%20}"
+                fi
+            }
+
+            resolve_jf_plugin() {
+                local requested="$1"
+                if ! command -v python3 >/dev/null 2>&1; then
+                    return 1
+                fi
+
+                printf '%s' "$PLUGIN_CATALOG" | python3 - "$requested" <<'PY'
+import json, sys
+
+wanted = sys.argv[1].strip().lower()
+try:
+    payload = json.load(sys.stdin)
+except Exception:
+    sys.exit(1)
+
+items = payload.get("Items", payload) if isinstance(payload, dict) else payload
+if not isinstance(items, list):
+    sys.exit(1)
+
+for item in items:
+    if not isinstance(item, dict):
+        continue
+    name = str(item.get("name", item.get("Name", ""))).strip()
+    guid = str(item.get("guid", item.get("Guid", ""))).strip()
+    if name.lower() == wanted:
+        print(name)
+        print(guid)
+        sys.exit(0)
+
+sys.exit(1)
+PY
+            }
+
             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)
+                local plugin_info plugin_guid resolved_name
+                plugin_info="$(resolve_jf_plugin "$plugin_name" || true)"
+                resolved_name="$(echo "$plugin_info" | sed -n '1p')"
+                plugin_guid="$(echo "$plugin_info" | sed -n '2p')"
 
-                if [[ -z "$plugin_guid" ]]; then
+                if [[ -z "$resolved_name" ]]; 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
+                local install_result encoded_name install_url
+                encoded_name="$(url_encode "$resolved_name")"
+                install_url="http://localhost:8096/Packages/Installed/$encoded_name"
+                if [[ -n "$plugin_guid" ]]; then
+                    install_url="${install_url}?assemblyGuid=$plugin_guid"
+                fi
+
                 install_result=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
-                    "http://localhost:8096/Packages/Installed/$plugin_name" \
+                    "$install_url" \
                     -H "X-Emby-Token: $JF_API_KEY" 2>/dev/null || echo "000")
 
                 if [[ "$install_result" =~ ^2 ]]; then
-                    log "$plugin_name plugin installed"
+                    log "$resolved_name plugin installed"
                 else
-                    warn "$plugin_name: install returned HTTP $install_result"
+                    warn "$resolved_name: install returned HTTP $install_result"
                     warn "  Install manually: Administration > Plugins > Catalog > $plugin_name"
                 fi
             }

scripts/health-check.sh

@@ -133,8 +133,8 @@ if [[ "$MEDIA_SERVER" == "jellyfin" ]]; 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
+            jellystat_http=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "http://localhost:3000/api/getConfiguration" 2>/dev/null)
+            if [[ "$jellystat_http" =~ ^(200|401|403)$ ]]; then
                 echo -e "  ${GREEN}OK${NC}  Jellystat"
                 ((PASS++))
             else

scripts/refresh-image-lock.sh

@@ -10,7 +10,7 @@ LOCK_FILE="$SCRIPT_DIR/IMAGE_LOCK.md"
 ENV_FILE="$SCRIPT_DIR/.env"
 
 PROFILES=(autoupdate music jellyfin)
-OPTIONAL_SERVICES=(watchtower jellyfin)
+OPTIONAL_SERVICES=(watchtower jellyfin jellystat jellystat-db)
 MUSIC_SERVICES=(lidarr tidarr)
 
 for cmd in docker awk sed mktemp; do

scripts/upgrade-from-basic.sh

@@ -287,6 +287,8 @@ if [[ "$MEDIA_SERVER" == "plex" ]]; then
     echo "  2. Configure Tdarr at http://localhost:8265"
 else
     echo "  1. Configure Tdarr at http://localhost:8265"
+    echo "  2. Open Jellystat at http://localhost:3000 and connect to http://jellyfin:8096"
+    echo "  3. If prompted, restart Jellyfin to finish Intro Skipper/TMDb Box Sets plugin activation"
 fi
 echo ""
 echo "Rollback (if needed):"