From 3c13d3e8e976429e034f2c3acc6bbb15e2520540 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sun, 14 Jun 2026 22:32:03 +0200 Subject: [PATCH] docs: REPORT for userdata layout repoint Co-Authored-By: Claude Opus 4.8 (1M context) --- REPORT.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 REPORT.md diff --git a/REPORT.md b/REPORT.md new file mode 100644 index 0000000..449922b --- /dev/null +++ b/REPORT.md @@ -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 = /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.