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