jellyfin: scan on download completion — inotify cannot work over NFS

Finished downloads stopped appearing in Jellyfin after the 2026-08-30 storage move, and everything looked healthy: the file was on nas, visible through NFS inside the container, and /media/downloads is a configured library. The cause is that Jellyfin watches libraries with inotify, which only reports changes made through the local mount — transmission now writes on nas while jellyfin-server reads over NFS on nuc, so no event ever reaches it. EnableRealtimeMonitor is true and SupportsLibraryMonitor reports true, which is why it looks fine. Previously both shared one local dataset on nuc and it worked. transmission now calls Jellyfin's /Library/Refresh via script-torrent-done. The hook always exits 0 and never blocks (transmission runs it synchronously; a hanging hook stalls the daemon), and both the success and missing-key paths are tested. nuc is usually powered off, so a failed request is expected and logged rather than treated as an error — the scheduled scan catches up. Also records that nuc's mount is read-only, so reorganising downloads into movies/tv-shows must now happen on nas, and the ordered checklist for "my download is not in Jellyfin" — the first three checks all passed when this was hit, which is what made it confusing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 20:21:36 +02:00
parent 1721d7b05d
commit 9468f30f92
2 changed files with 107 additions and 0 deletions
@@ -199,3 +199,70 @@ incus exec transmission-bt -- bash -c "ping -c1 -W2 8.8.8.8 || echo kill-switch
 - The image server check can make `incus launch` hang on slow WAN —
  launching from the cached image fingerprint (`incus image list`)
  bypasses it.
+
+## Jellyfin library scan on completion (2026-08-31)
+
+Jellyfin cannot notice finished downloads by itself any more. It watches
+libraries with **inotify**, but since the media moved to nas the writer
+(transmission, here) and the reader (`jellyfin-server` on nuc, over NFS)
+are on different machines — an inotify event never crosses that. Before
+the move both shared one local dataset on nuc, so it just worked.
+
+So transmission tells Jellyfin explicitly, via
+`script-torrent-done`:
+
+```json
+"script-torrent-done-enabled": true,
+"script-torrent-done-filename": "/usr/local/bin/jellyfin-scan.sh"
+```
+
+The hook POSTs to Jellyfin's `/Library/Refresh`:
+
+```sh
+#!/bin/sh
+KEY_FILE=/etc/jellyfin-scan.key
+JF=http://192.168.0.5:8096
+NAME="${TR_TORRENT_NAME:-unknown}"
+[ -r "$KEY_FILE" ] || { logger -t jellyfin-scan "no readable key file; skipped ($NAME)"; exit 0; }
+KEY=$(tr -d " \t\r\n" < "$KEY_FILE")
+if curl -fsS -m 15 -X POST -H "X-Emby-Token: $KEY" "$JF/Library/Refresh" >/dev/null 2>&1; then
+    logger -t jellyfin-scan "library scan requested after: $NAME"
+else
+    logger -t jellyfin-scan "library scan request FAILED (nuc off?) after: $NAME"
+fi
+exit 0
+```
+
+Design points, each of which matters:
+
+- **Always `exit 0`, never block.** transmission runs the hook
+  synchronously; a hanging or failing hook stalls the daemon. Both paths
+  are tested — success and unreadable-key both exit 0.
+- **nuc is usually powered off.** The request then fails, logs
+  `FAILED (nuc off?)`, and Jellyfin picks the file up on its next
+  scheduled scan. Not an error worth alerting on.
+- **The key file is `640 root:debian-transmission`** — the hook runs as
+  `debian-transmission`, so it must be group-readable, and nothing wider.
+- Reachable despite the kill switch: `192.168.0.5` is on the directly
+  connected LAN, so it needs no default route.
+
+Verify:
+
+```sh
+incus exec transmission-bt -- su -s /bin/sh debian-transmission \
+    -c 'TR_TORRENT_NAME=selftest /usr/local/bin/jellyfin-scan.sh'
+incus exec transmission-bt -- journalctl -t jellyfin-scan -n 3
+```
+
+**Rotating the key**: create a new one in Jellyfin (Dashboard → API Keys),
+then
+
+```sh
+printf %s '<new-key>' | incus exec transmission-bt -- sh -c \
+  'umask 027; cat > /etc/jellyfin-scan.key; chown root:debian-transmission /etc/jellyfin-scan.key'
+```
+
+⚠️ Edit `settings.json` only while the daemon is **stopped** —
+transmission rewrites the whole file on shutdown and will silently
+discard changes made underneath it.
+