diff --git a/AGENTS.md b/AGENTS.md index eb0b9ea..9d36f00 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -808,6 +808,7 @@ per-attempt page and no per-swap ledger anywhere else. | Dankclaw kernel posture (`iommu=pt` since 2026-10-18) | `serverAppConfigs-docs/LLM/dankclaw-iommu-translation-off.md` | | Deployment flow | `serverAppConfigs-docs/Architecture/Deployment Flow.md` | | Movie-library relayout (Jellyfin format, Dankserver) | `serverAppConfigs-docs/Dankserver/Media Relayout.md` | +| SSD-backed metadata view (Jellyfin writes, Plex reads, Dankserver) | `serverAppConfigs-docs/Dankserver/Media Metadata View.md` | There is no page for a retired endpoint and no change diary. A payload swap appends one row to the live endpoint's **Eras** table; when the endpoint itself @@ -850,5 +851,6 @@ history. | Benchmarking (only when ordered) | **Stop and mask the service first**, bench, unmask, restart, verify health. | | Deleting a file | **Move it to trash** — `.AGENTTRASH/` (in-repo) or `~/.AGENTTRASH/YYYYMMDD-topic`. Never `rm`. | | Relayout the movie library | **Census → plan → read the exceptions → `scripts/media-apply.py`** — renames only, journal before every move; never hand-rename, never copy. | +| Making media metadata visible to both media servers | **Bind `/mnt/media`** — the overlay `scripts/media-view.sh` installs (array below, NVMe above). Never write the array; never delete through the view. | | Tests exist | **Run them** — verify tests pass after every change. Do not commit failing tests. | | Real secrets | **Never commit** — host `.env` files; `.env.example` holds placeholders only. | diff --git a/serverAppConfigs-docs/Dankserver/Jellyfin.md b/serverAppConfigs-docs/Dankserver/Jellyfin.md index ddeb7e1..e93bd87 100644 --- a/serverAppConfigs-docs/Dankserver/Jellyfin.md +++ b/serverAppConfigs-docs/Dankserver/Jellyfin.md @@ -1,9 +1,9 @@ --- type: reference title: Jellyfin -description: "Jellyfin on Dankserver: quadlet unit, entropy-volume data layout, ports, client access, hardware-transcode status." +description: "Jellyfin on Dankserver: quadlet unit, overlay metadata view layout, ports, access, hardware-transcode status." tags: [jellyfin, dankserver, media-server] -timestamp: 2026-09-03T00:00:00Z +timestamp: 2026-10-30T00:00:00Z --- # Jellyfin @@ -26,7 +26,7 @@ public vhost `jelly.franksdank.cloud` behind the [[Anubis]] guard chain → | Image | `ghcr.io/jellyfin/jellyfin:latest` | | Network | `dankserver_appnet`; publishes 8096/tcp, 8920/tcp, 7359/udp, 1900/udp | | Data roots | `/home/dank/Containers/jellyfin/config:/config`, `/home/dank/Containers/jellyfin/cache:/cache` | -| Media | `Volume=/mnt/entropy:/data:ro` — the whole [[Entropy Volume]] mounted read-only; nothing automated writes to it | +| Media | `Volume=/mnt/media:/data` — the [[Media Metadata View]] overlay, **writable**; sidecars land on the NVMe, the [[Entropy Volume]] array underneath stays read-only and untouched | | GPU | none — no `AddDevice`; CPU decode only (jellyfin-ffmpeg path) | | Env quirks | `DOTNET_SYSTEM_IO_DISABLEFILELOCKING=true`, `LD_PRELOAD=libjemalloc.so.2`, `MALLOC_TRIM_THRESHOLD_=131072` kept verbatim from the compose-era container (zero-drift cutover) | | Health | `curl -f http://localhost:8096/health` every 30 s | @@ -36,20 +36,23 @@ public vhost `jelly.franksdank.cloud` behind the [[Anubis]] guard chain → ``` /home/dank/Containers/jellyfin/config -> /config (JELLYFIN_DATA_DIR) /home/dank/Containers/jellyfin/cache -> /cache (JELLYFIN_CACHE_DIR, XDG_CACHE_HOME) -/mnt/entropy -> /data (read-only media volume) +/mnt/media -> /data (the SSD-backed overlay view) ``` -Library folders point at `/data` paths; because the mount uses the same -absolute path as on the host, library paths survive container recreation. +Library folders point at `/data` paths, which are the view's paths: stable +across container recreation, and identical to the raw array layout below it. -`Local metadata` — save metadata to media folders — cannot work against a `ro` -mount, and it is enabled: every item update logs -`System.IO.IOException: Read-only file system : '/data/Movies//movie.nfo'`. -The exception lands in the sidecar saver, after the database row is written, so -indexing proceeds anyway — a 2026-10-30 scan dropped stale records and added -episodes while these lines filled the log. Expected noise, not a fault: if it -ever needs silencing, turn the saver off under *Library → Metadata* rather than -making `/data` writable. +`Local metadata` — save metadata to media folders — is enabled, and it works +because `/data` is the [[Media Metadata View]] rather than the read-only array: +`movie.nfo`, `tvshow.nfo`, `episode.nfo` and artwork are written once, on the +NVMe upper layer, and [[Plex]] reads the same files. Jellyfin is the fleet's +only metadata writer. + +**Failure signature:** `System.IO.IOException: Read-only file system : +'/data/Movies//movie.nfo'` means the container is binding the raw array +instead of the view — the view is unmounted or the quadlet drifted. That used to +be the expected state (pre-view, every item update logged it); today it is a +fault. Run `scripts/media-view.sh status`. ## Ports & access diff --git a/serverAppConfigs-docs/Dankserver/Media Metadata View.md b/serverAppConfigs-docs/Dankserver/Media Metadata View.md new file mode 100644 index 0000000..aab1a6c --- /dev/null +++ b/serverAppConfigs-docs/Dankserver/Media Metadata View.md @@ -0,0 +1,105 @@ +--- +type: reference +title: Media Metadata View +description: "The SSD-backed overlay the two media servers read and write: shape, guards, commands, laws, rollback." +tags: [dankserver, media-server, jellyfin, plex, storage] +timestamp: 2026-10-30T00:00:00Z +--- + +# Media Metadata View + +`/mnt/media` is an OverlayFS merge of the media library: the RAID6 array below, +a directory on the NVMe above. It exists so [[Jellyfin]] can write Kodi-format +sidecars (`movie.nfo`, `tvshow.nfo`, `episode.nfo`, artwork) that [[Plex]] can +read. Sidecar metadata is only useful sitting next to the media file, and the +array is read-only and slow — so the bytes stay there and the *writes* land on +SSD. One tree to both servers, one copy of the media. + +## Shape + +| Item | Value | +|---|---| +| Lower layer | `/mnt/entropy` — the RAID6 array, source of truth, never written | +| Upper layer | `/var/lib/media-meta/upper` — NVMe; every write lands here | +| Work dir | `/var/lib/media-meta/work` — overlayfs internals, same filesystem | +| Mount point | `/mnt/media`, unit `mnt-media.mount` (`WantedBy=local-fs.target`) | +| Repo source | `dankserver/host/systemd/mnt-media.mount` — host copy is generated state | +| Installer | `scripts/media-view.sh` — `plan` / `install` / `verify` / `status` / `reap` | +| Written by | Jellyfin only (Plex binds read-only); nothing else in the fleet touches it | + +Both consumers guard the view with +`UnitConfigItem=ConditionPathIsMountPoint=/mnt/media`, and `scripts/deploy.sh +dankserver --service jellyfin|plex` calls `media-view.sh install` + `verify` +before it restarts either container. + +| Consumer | Bind | Mode | Why that path | +|---|---|---|---| +| [[Jellyfin]] | `/mnt/media:/data` | rw | It is the metadata writer; its sidecars become SSD bytes | +| [[Plex]] | `/mnt/media:/mnt/entropy` | ro | Every path in the PMS database was recorded as `/mnt/entropy/...`; only the HOST side of the bind moved, so its database still resolves | + +## Commands + +```bash +scripts/media-view.sh plan # print the resolved shape, touch nothing +sudo scripts/media-view.sh install # create dirs, install the unit, mount, enable +scripts/media-view.sh verify # is /mnt/media really the overlay? (deploy gate) +scripts/media-view.sh status # mount options + upper-layer size/file count +scripts/media-view.sh reap # list ghost metadata (media moved, sidecars left) +sudo scripts/media-view.sh reap --apply # move ghosts to the SSD trash, never delete +``` + +`--upper-base DIR` and `--lower DIR` relocate the layers; the defaults are the +host values above. + +## Laws + +- **The upper layer must sit on non-rotational storage.** `install` and `verify` + refuse via `lsblk -dno ROTA` if the upper base lives on the array: an overlay + whose upper is the spinners is the original problem with extra steps, and it + silently turns every metadata write back into a seek. +- **Never mount the view over an unmounted lower.** `RequiresMountsFor=/mnt/entropy` + plus the container `ConditionPathIsMountPoint` guards: an empty `lowerdir` + presents an *empty library* as truth, and a media scan would then clear the + database of everything. +- **Never delete through `/mnt/media`.** A delete writes an overlayfs whiteout + (`.wh.`) in the upper layer, which hides the array's copy without + removing it — the file reappears the moment the view is unmounted, and the + upper layer now carries a landmine. Deletions belong on the raw path + (`/mnt/entropy`), which the relayout tool already treats as the only writer. + `reap` refuses to remove whiteouts and only warns about them. +- **A relayout must be followed by `reap`.** Renames happen on the raw path, so + sidecars the view already wrote stay at the old coordinates: a ghost folder + the servers browse and find nothing in. `reap` lists upper-layer directories + with no counterpart below and moves them (with their subtree) into a dated + `.AGENTTRASH/` under the SSD base. It is recursive and file-safe: a sidecar + that exists only above is normal, so only *directories* are candidates. +- **File-watcher events do not cross the overlay.** Plex's NFO agent and + Jellyfin's real-time monitor see inotify events for writes that land *in the + upper layer*, not for changes on the array underneath. After any relayout or + externally-written metadata, trigger a library refresh — see + [[Media Relayout]] for the refresh procedure. + +## Failure signatures + +| Symptom | Meaning | +|---|---| +| `jellyfin.service` / `plex.service` show `ConditionPathIsMountPoint=... was not met` and stay inactive | `/mnt/media` is not mounted. Do not start them anyway: `scripts/media-view.sh install`, then `verify`. | +| Jellyfin log: `Read-only file system : '/data/Movies/…/movie.nfo'` | The container is binding the raw array, not the view — the quadlet drifted back or the view is gone. `media-view.sh status`. | +| A folder appears in a media server with artwork/`.nfo` but no video | Ghost metadata from a relayout. `media-view.sh reap`. | +| `verify` prints `refused: /mnt/media is not a mountpoint` | Someone made a plain directory there. That is the fail-closed guard working; remove it and install. | + +## Rollback + +Revert the commit that pointed the two quadlets at the view and re-deploy both +services — they bind `/mnt/entropy` read-only again, which is the pre-view +shape. The NVMe upper layer can stay: nothing reads it once the binds are back, +and it holds no state either server needs. Removing the mount alone +(`systemctl stop mnt-media.mount`) is safe while no container binds it, and the +array is never modified by any of this. + +## Links + +- [[Jellyfin]] — the metadata writer; its data layout section. +- [[Plex]] — the read-only consumer; in-place bind-mount history. +- [[Media Relayout]] — the tool that moves media on the raw path and the reason `reap` exists. +- [[Entropy Volume]] — the array underneath. diff --git a/serverAppConfigs-docs/Dankserver/Media Relayout.md b/serverAppConfigs-docs/Dankserver/Media Relayout.md index 64e824c..a381612 100644 --- a/serverAppConfigs-docs/Dankserver/Media Relayout.md +++ b/serverAppConfigs-docs/Dankserver/Media Relayout.md @@ -250,6 +250,18 @@ show. A name whose marker is `Part 2` is a film and stays put. path outside `--root`, and a journal shared with the movie relayout would undo both runs when only one of them is wanted. +- **Sidecar metadata does not follow a rename, because it lives on another + filesystem.** The media servers write `.nfo` and artwork through the + [[Media Metadata View]] (NVMe upper layer); this tool moves bytes on the raw + array path. After any sweep or TV move, run `scripts/media-view.sh reap`, then + the same command with `--apply`: the sidecars left at the old coordinates become + ghost folders — artwork and an `.nfo` with no video — that both servers browse + and report as content. +- **Nothing deletes through `/mnt/media`.** A delete there writes an overlayfs + whiteout in the upper layer, which hides the array's copy without removing it; + the file returns when the view is unmounted. Deletions in this pipeline happen + on the raw path only, which is what the journal can undo. + ## Rollback One command, from the journal of the run: @@ -260,7 +272,7 @@ file cannot be accounted for. A rolled-back journal refuses to roll back twice. ## See Also -[[Jellyfin]], [[Plex]], [[Entropy Volume]], [[Testing Policy]], [[Storage Policy]] +[[Jellyfin]], [[Plex]], [[Media Metadata View]], [[Entropy Volume]], [[Testing Policy]], [[Storage Policy]] ## Citations diff --git a/serverAppConfigs-docs/Dankserver/Plex.md b/serverAppConfigs-docs/Dankserver/Plex.md index a6d79a1..dd36582 100644 --- a/serverAppConfigs-docs/Dankserver/Plex.md +++ b/serverAppConfigs-docs/Dankserver/Plex.md @@ -4,7 +4,7 @@ description: "Plex Media Server is a **containerized media server on Dankserver* tags: - dankserver - plex -timestamp: 2026-10-21 +timestamp: 2026-10-30 --- # Plex @@ -13,7 +13,8 @@ Plex Media Server is a **containerized media server on Dankserver**: a podman quadlet (`plex.service`) under the systemd **user** generator, generated from `dankserver/plex/quadlet/plex.container`. It shares the host with a second live media server, [[Jellyfin]] (`jellyfin.service`, listening on 8096); both serve -from the same read-only Entropy Volume mount. +from the same tree — the [[Media Metadata View]] overlay — so the Kodi-format +sidecars Jellyfin writes are the files Plex reads, with no copy and no sync. **Host:** Dankserver — **Ports:** 32400/tcp (PMS web + API), 32400 is the only port PMS needs for client streaming; LAN clients connect directly, @@ -26,7 +27,7 @@ public traffic can be fronted by Caddy like every other vhost. | Runtime | podman quadlet, `plex.service` (user manager) — migrated from the native `plexmediaserver.service` OS-package unit (2026-09) | | Image | `lscr.io/linuxserver/plex:1.43.5.11029-6bf8af3f0-ls329` (pinned; verified == the registry's `latest` manifest digest at pin time: `sha256:8f655bad…e9e2334`) | | Data root | `/var/lib/plexmediaserver` bind-mounted **in place** as `/config` (RW) — the migration moved zero bytes | -| Media | `/mnt/entropy` mounted at the same absolute path **read-only** — every library path in the PMS database stayed valid, zero re-scan | +| Media | `/mnt/media` (the [[Media Metadata View]] overlay) bound at the same absolute path `/mnt/entropy` **read-only** — every library path in the PMS database stayed valid, zero re-scan | | Identity | fleet rootless model — container root maps to the `dank` user (1000:1000); the deployer chowns the data root on first cutover | | Port | `32400/tcp` published on `0.0.0.0` — zero client reconfiguration | | Network | `dankserver_appnet`, alias `plex`; Tautulli reaches it at `http://plex:32400` | @@ -38,7 +39,8 @@ public traffic can be fronted by Caddy like every other vhost. The migration moved zero bytes: the container bind-mounts the native data root where it already lived, and the media archive re-mounts at -`/mnt/entropy` inside the container, so every absolute library path in the +`/mnt/entropy` inside the container — only the HOST side of that bind has moved +(array, then the overlay view), so every absolute library path in the PMS database keeps resolving. The one metadata change: rootless podman cannot map the real host uid 997, so the fleet model applies — container root runs as the `dank` user, and the deployer adopts the data root with diff --git a/serverAppConfigs-docs/index.md b/serverAppConfigs-docs/index.md index e11da97..a5e7551 100644 --- a/serverAppConfigs-docs/index.md +++ b/serverAppConfigs-docs/index.md @@ -49,8 +49,9 @@ is a locator: one row, one clause, no numbers. | [[Copyparty]] | Copyparty is a lightweight file server and media streamer that runs as a single Python binary. | | [[Dankserver Stack]] | Service inventory and routing overview for the media and library host. | | [[Entropy Volume]] | The Dankserver entropy volume is a RAID-backed LUKS filesystem mounted at | -| [[Jellyfin]] | Jellyfin on Dankserver: quadlet unit, entropy-volume data layout, ports, client access, hardware-transcode status. | +| [[Jellyfin]] | Jellyfin on Dankserver: quadlet unit, overlay metadata view layout, ports, access, hardware-transcode status. | | [[mariadb]] | The MariaDB backend for RomM: quadlet unit, network alias, env-file secret handling, and the backup path. | +| [[Media Metadata View]] | The SSD-backed overlay the two media servers read and write: shape, guards, commands, laws, rollback. | | [[Media Relayout]] | Census, plan and apply the movie library into Jellyfin format, and move TV out of it: the gates, refusals, rollback. | | [[Plex]] | Plex Media Server is a **containerized media server on Dankserver**: a podman | | [[redis]] | The Redis cache and task queue for RomM: quadlet unit, network alias topology, and the backup path. |