docs: REPORT for userdata layout repoint

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 22:32:03 +02:00
parent c99070c105
commit 3c13d3e8e9
1 changed files with 39 additions and 0 deletions
@@ -0,0 +1,39 @@
+# REPORT — userdata layout repoint (2026-06-14)
+
+Repointed every customer-content mount off `${HDD_PATH}/media` onto the new `${USERDATA_PATH}/...`
+convention (controller v0.66.x injects `USERDATA_PATH = <namespace root>/userdata`). Trunk-based on
+`main` (catalog = commits, no semver). Pairs with felhom-controller v0.66.1.
+
+> Validate against the pushed compose/.felhom.yml at file:line.
+
+## Commits
+- `69611ce` — repoint 12 composes + update touched `.felhom.yml` first_steps/comments.
+- `0d60a5c` — komga + audiobookshelf: revert `user:1000` → root (live try-then-fallback).
+- `c99070c` — komga + audiobookshelf: add `security_opt: no-new-privileges:true` (root hardening).
+
+## Per-app changes
+| App | media/ingest mount(s) | run-identity |
+|---|---|---|
+| jellyfin / emby / plex | `${USERDATA_PATH}/media:/media:ro` | jellyfin/plex root; emby UID/GID 1000 |
+| navidrome | `${USERDATA_PATH}/media/music:/music:ro` | root |
+| audiobookshelf | `media/audiobooks` + `media/podcasts` (RW) | **root** (user:1000 fell back) + no-new-privileges |
+| komga | `media/comics:/data` (RW) | **root** (user:1000 fell back) + no-new-privileges |
+| calibre-web | library `media/books` + ingest `import/calibre` (RW) | PUID/PGID 1000, **UMASK=002** |
+| radarr | `media/movies` + `downloads` (RW) | PUID/PGID 1000, **UMASK=002** |
+| sonarr | `media/tv` + `downloads` (RW) | PUID/PGID 1000, **UMASK=002** |
+| romm | ROM library → `userdata/roms` (RW); `resources` stays in appdata | root |
+| immich | + external `media/photos:/external/photos:ro`; managed upload stays in appdata | root |
+| paperless-ngx | consume → `import/paperless`; media/export stay in appdata | USERMAP_UID/GID 1000 |
+| nextcloud | **unchanged** (fully app-managed) | — |
+
+## Notes
+- **komga + audiobookshelf**: `user: "1000:1000"` was tried but crash-looped (their named config/metadata
+  volumes are Docker-created root-owned; no PUID-style root-init). Reverted to root + `no-new-privileges`.
+  They rely on the controller's setgid 2775 userdata dirs → files land group 1000 (FileBrowser
+  browses/reads; full group-write only on the PUID-1000 apps). Verified live on guest 9201.
+- **immich external library**: the `media/photos:/external/photos:ro` mount only makes the files visible.
+  The library must be **registered** in Immich (Administration → External Libraries) — a post-deploy admin
+  step; compose cannot do it. Flagged in the compose + `.felhom.yml`. Photos sharing is "mount ready,
+  registration pending". Live deploy deferred (guest 9201 has 2 GiB RAM; immich needs ~4 GiB).
+- Folder names are ASCII, no spaces (`tv`, not "tv shows") so they flow cleanly through `${}` interpolation,
+  shell, and the controller's rsync merge walk.