# 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.