felhom.eu/documentation/backlog/SPEC-app-data-placement-2026-08-21.md

SPEC — where an app's data is placed, and who decides

⚠ CORRECTED 2026-08-22 — THE MEASUREMENTS STAND, THE FRAMING WAS WRONG

This document called a documented architectural decision a defect. It is left in place rather than rewritten, because a document that quietly changes its mind teaches nobody. Every measurement below is good and was re-checked on 2026-08-22; the corrections are marked inline as [CORRECTED 2026-08-22].

What it got wrong. It treated the absence of a storage field on 40 of 53 templates as a choice being denied. There is no choice to deny. The architecture states the placement rule and states it as enforced:

"App data placement is per-volume, not per-app: .felhom.yml classifies each volume hot (DB/config/cache → fast storage, enforced) vs bulk (media/files → may be slow). A photo app's DB stays on SSD while its blobs go to the USB." — documentation/architecture/01-topology-and-trust.md:150-152

The 40 templates are all-hot apps: their data is app internals — database, config, cache — and hot data belongs on fast storage inside the guest, by design. The 13 with a configurable path are the media and library apps, where bulk content legitimately belongs on an attached drive. The split is not 40 apps missing a feature; it is the hot/bulk contract working.

And the guest volume is deliberately its own volume, so that filling it cannot stop the operating system: the golden ships a small OS rootfs plus a single data volume at /var/lib/felhom (felhom-agent/configs/build-golden.sh:29-40), and a capture that would exhaust it is refused per app rather than allowed to stop the container runtime (documentation/architecture/00-capability-map.md:94, PROVEN-LIVE 2026-08-03).

One real defect survives the correction and is unchanged: settings.go:453 says // new apps use this by default and no app has ever used it. That is §2.2 below and it is now filed on its own, scoped by measurement rather than by assumption — see the register.

What still needs a ruling: far less than §5 implies. See the corrected §5.

Filed 2026-08-21. Status: SPECIFICATION ONLY — nothing here is implemented, and nothing here may be implemented without the operator's ruling. It deserves its own session.

Measured on demo-hp (HP t740, controller 0.216.0, agent 0.130.0) on 2026-08-21, during and after the box was reinstalled. Every claim below carries the file:line or the live observation it came from.

---

1. What was found

An operator walking the deploy screens saw that OpenGist's deploy page offered only Domain and Subdomain — no storage field of any kind — while the Drives page showed the NVMe at /mnt/felhom-drives/hdd_1 marked Alapértelmezett and Aktív, with "1 alkalmazás használja". OpenGist's data and its first-tier backup were both under /mnt/sys_drive/.

The first hypothesis — that a customer had typed a bad path, or had failed to choose a drive — is wrong. There is nothing to type and nothing to choose. The finding is narrower and worse:

The configured default data store is not consulted on the deploy route at all.

[CORRECTED 2026-08-22] The observation is right; the conclusion drawn from it was not. There is nothing to choose because these apps have no bulk volume to place — the hot/bulk contract (01-topology-and-trust.md:150-152) puts their data on fast storage inside the guest by design, and OpenGist is a pure hot app. The sentence in the quote above is still true as a statement about the deploy route, and it is still a defect for the 13 templates that DO take a path — that is the real remainder, established in Part 4 of the 2026-08-22 session and filed separately. For the other 40 it is not a defect at all: a default drive cannot be "consulted" for an app that has no path to put it in.

2. The four measured facts

2.1 The affected class is 40 of 53 catalogue templates

find . -name '.felhom.yml' | wc -l                          -> 53
grep -rl 'env_var: HDD_PATH' --include='.felhom.yml' . | wc  -> 13
                                                    do not  -> 40

The 13 that declare a data path: audiobookshelf calibre-web emby immich jellyfin komga navidrome nextcloud paperless-ngx plex radarr romm sonarr. All media libraries. The same 13 carry a backup: block.

Negative control: grep -c HDD_PATH templates/opengist/{.felhom.yml,docker-compose.yml} returns 0 for both — such an app cannot receive an HDD_PATH even if one were supplied.

2.2 The default store is a preference with no effect on what it names

settings.GetDefaultStoragePath() (hub-side equivalent none; controller internal/settings/settings.go:1196) has exactly three non-test callers:

Caller	What it actually decides
controller/cmd/controller/main.go:410	which drive the metrics collector measures
controller/internal/web/server.go:733 (primaryHDDPath)	the dashboard SystemInfo panel (handlers.go:176, 732, 876)
controller/internal/web/handler_export_upload.go:154	where an uploaded .fab import lands

grep -nE 'GetDefaultStoragePath|primaryHDDPath|IsDefault' controller/internal/stacks/deploy.go controller/internal/stacks/manager.go returns nothing.

The field's own comment at internal/settings/settings.go:453 reads // new apps use this by default. No new app has ever used it. That comment is an invariant with no test pinning it — the class CLAUDE.md names.

Where the data actually goes: a named Docker volume on the guest root filesystem. Verified live:

privatebin   volume src=/var/lib/docker/volumes/privatebin_privatebin_data/_data
calibre-web  bind   src=/mnt/felhom-drives/hdd_1/userdata/media/books

withPathVars (internal/stacks/deploy.go:600-607) injects USERDATA_PATH only if hdd != "".

2.3 The first-tier backup follows the data onto the same disk

GetAppDrivePath (internal/backup/backup.go:324-334): no HDD_PATH → returns m.systemDataPath. Live:

/mnt/sys_drive/felhom-data/backups/primary/opengist/manifest.json
   drive='/mnt/sys_drive'  namespace_root='/mnt/sys_drive/felhom-data'

So for these 40 apps the data and its nearest copy sit on the same physical device, reached by a customer doing nothing wrong.

[CORRECTED 2026-08-22] — and be precise about which risk is real.

The device claim is true. The framing "by accident" was not. Since R-165 (golden build-golden.sh v3.0.0, proven live 2026-08-03) the guest carries a small OS rootfs plus ONE data volume at /var/lib/felhom; /var/lib/docker and /mnt/sys_drive are two binds of that same volume, and the script says so in terms — "There is deliberately no mp1" (build-golden.sh:99). The mp0/mp1 split this document's era assumed was retired six days before this document was written and is on no current box.

Which risk is real, stated exactly:

• A failure of the physical disk loses both the app's data and its first-tier copy. REAL, and it is what the off-site and whole-machine tiers exist for. It is not specific to the 40-class: a drive-resident app's unit lives beside its data on the drive too, deliberately, so a restore needs the drive and nothing else.
• A full data volume taking out the operating system. NOT REAL, and it was the overstated one. The OS rootfs is a separate volume, and the capture floor refuses a capture that would exhaust the data volume rather than letting it stop the container runtime (00-capability-map.md:94). Watched working on 2026-08-21: with /var/lib/felhom at 99% the reserve refused one app per run and told the hub, while all 15 containers stayed healthy.

So the sentence "The defect is not Tier 1's rule; it is that these apps are on the system drive in the first place" below is withdrawn. Being on the guest's data volume is where hot data belongs.

The project already treats that posture as unacceptable — for the other tier. Tier 2 refuses it outright at internal/backup/tier2.go:329, recording a kiválasztott cél ugyanazon a fizikai lemezen van. Tier 1 has no such notion, and for a drive-resident app it is correct that it has none: the unit is meant to live beside the data so a restore needs the drive and nothing else. The defect is not Tier 1's rule; it is that these apps are on the system drive in the first place.

2.4 The Drives page count cannot include most apps

countAppsUsingPath (internal/web/handlers.go:2118-2131) counts only appCfg.Env["HDD_PATH"] == storagePath. An app with no HDD_PATH can never match any drive.

So "1 alkalmazás használja" truthfully means "1 of the apps that CAN use a drive does", and the 40-of-53 class is invisible on that page. The code already names the class deliberately at handlers.go:2140: // An app with no HDD_PATH (SSD-resident) is never "missing". This is an unstated design, not an accident.

3. Is that class protected?

Whole-machine tier: yes. Verified by df, not assumed — /mnt/sys_drive, /var/lib/docker and /var/lib/felhom are all on pve-vm-9201-disk-1, which is mp0 in /etc/pve/lxc/9201.conf with backup=1. Named volumes and sys-drive units land in the guest backup.

Off-site tier: covered by code, NOT demonstrated. runVolumeDumps (internal/backup/backup.go:607+) iterates every deployed unprotected stack with named volumes; its drive-state gates use GetAppDrivePath, which returns the system path — neither disconnected nor decommissioned, so the gates pass. On paper these apps are dumped.

It has not been seen happen. All three units on the box reported volume_dumps: None, db_dumps: None — including calibre-web, which is on the data drive. No nightly dump run had occurred on a box one hour old. This is recorded as unknown rather than fine.

4. What is ruled, and what is not

Ruled and shipped 2026-08-21 (R-351, controller): the deploy page now states where the app's data will live before the button is pressed — naming the system drive for the 40-class, and the selected drive for the 13. Visibility only. No placement changed. Nothing was migrated.

Explicitly NOT done, and not to be done without a ruling:

• No storage selector was added for apps that do not need one. The field is not the point; the placement is. Adding a drive dropdown to 40 apps whose compose never references a path would be a control that changes nothing.
• Deployment is NOT refused when no drive is registered. An earlier draft of this session recommended that and it was withdrawn: it was built on the belief that the customer had failed to choose. They had no choice to make. Refusing 40 of 53 apps for a drive they cannot use would break the ordinary path to fix a hazard the customer never touched.
• No placement change, no migration. Moving where apps write has consequences for every existing deployment on every box in the fleet.

5. The open question this document exists to hand over

[CORRECTED 2026-08-22] — THIS QUESTION IS ALREADY ANSWERED, AND THE ANSWER IS NO.

The architecture answers it: hot data (DB/config/cache) belongs on fast storage inside the guest and that placement is enforced, not preferred (01-topology-and-trust.md:150-152). A named-volume app is all-hot. Moving it to the attached drive would be moving hot data onto storage the same document classes as possibly-slow, and would put it outside the guest vzdump that currently protects it (01-topology-and-trust.md:154-156).

So points 1, 2 and 3 below are withdrawn as a live question. They remain a good record of what a change would have cost, which is why they are not deleted. Point 3 was already arguing against the premise of the question it sat under.

WHAT ACTUALLY STILL NEEDS YOUR RULING FROM THIS DOCUMENT: point 4 only, and it is smaller than it looks — IsDefault's comment must become true or go away, for the 13 apps it could apply to. That is filed as its own row with its scope measured rather than assumed. Point 5 (the Drives page count) needs no ruling: the count is honest, it is only easy to misread, and that is a wording question the design system already owns.

Everything else in this section: nothing to decide.

Should a named-volume app's data live on the default data drive rather than the system drive? (superseded — see the correction directly above)

Points the next session must settle, each of which is a reason this was not decided tonight:

1. It is a compose-template question, not only a controller question. A named volume (opengist_data:/opengist) has no path to redirect. Either the templates gain binds under ${USERDATA_PATH} — a 40-template catalogue change — or Docker's data-root moves, which relocates every container's storage including the controller's own.
2. Existing deployments. Any change must answer what happens to the apps already running on the system drive. Leaving them and changing only new installs creates two classes with no visible difference — which is how this defect became invisible in the first place.
3. The system drive is not always wrong. A small config-only app on the SSD is a reasonable placement; a media library is not. A rule that says "always the data drive" would move things that were fine.
4. IsDefault must either be consulted or removed. A setting that names a behaviour it does not have is worse than no setting. Whichever way the placement question goes, that field's comment at settings.go:453 has to become true or go away — with a test pinning it, since it has been a wish since it was written.
5. The Drives page count needs the same decision. Whatever the rule becomes, the page must stop implying that the apps it does not count are not using storage.

6. Evidence deliberately left in place

The OpenGist instance on demo-hp was to be left exactly where it was, as a real example of the defect on real hardware. It was removed by someone between 16:57 and 17:02 UTC on 2026-08-21 — ScanStacks: found stack "opengist" deployed=false from 17:02:58 onward — not by this session.

Its evidence survives: the recovery unit and manifest at /mnt/sys_drive/felhom-data/backups/primary/opengist/ are intact and carry drive='/mnt/sys_drive'. privatebin is now a live specimen of the same class on the same box, with its data at /var/lib/docker/volumes/privatebin_privatebin_data/_data.