posix: state follows storage.root; storage.stateDir for a deliberate split (#821) #827

Merged
Cordy merged 1 commit from fix-821b into main 2026-10-01 05:53:05 +00:00
Owner

Fixes #821 with options 2 + 3 (decided in review; research in the chat thread, summary below). Supersedes #825.

Behaviour

  • config.ResolveStateDir() (called in main after config/env/bootstrap are final): every path still at its /data/.cairn/… default is rebased onto the state directory:
    • storage.stateDir / CAIRN_STATE_DIR when set (source storage.stateDir);
    • posix: <storage.root>/.cairn (source storage.root) — identical to today with the default root;
    • s3: unchanged /data/.cairn (source default); state documents are in the bucket anyway.
  • Explicit paths are kept. Stay local by design: tusSpoolDir, peering.stagingDir (cleanup via #826), and bootstrap.json (how Cairn finds the root). Follow the state dir: all state files, pictures, preview cache, audit log, marks ledger.
  • <root>/.cairn is already a reserved root (internal/storage/reserved), so it is invisible on every user surface.
  • Upgrade: moveStateDir moves state left on /data/.cairn once (files + avatars/spaceimg/audit/marks), #154 adopt-or-refuse per file; retired copies stay as *.migrated; scratch, bootstrap and foreign files untouched.
  • Startup log: instance state directory (#821) dir=… from=….

Why (research): Vaultwarden (DATA_FOLDER, everything derives), Gitea (APP_DATA_PATH from WORK_PATH; a default outside the mounted volume lost data, fixed by a breaking change "the only way … to avoid users losing their data accidently"), Nextcloud (appdata inside datadirectory, and the opposite demand #32270/#3034 for a deliberate split → our stateDir), MinIO (.minio.sys beside the data).

Tests: config table test (default unchanged, moved root, stateDir wins, explicit paths kept, s3 untouched, look-alike prefix not rewritten); moveStateDir (moves state, retires old, leaves scratch/bootstrap/foreign files, idempotent, refuses on differing copies). Ran the binary with storage.root=/tmp/…/root: boots (previously it needed a writable /data), state lands in root/.cairn.

Docs: deployment.md "Where state lives" + "Splitting state from files on purpose", upgrade note, refusal list, backups paragraph (also drops the stale "versioning delegated to snapshots"). CHANGELOG v0.6.311.

Fixes #821 with options 2 + 3 (decided in review; research in the chat thread, summary below). Supersedes #825. **Behaviour** - `config.ResolveStateDir()` (called in main after config/env/bootstrap are final): every path still at its `/data/.cairn/…` default is rebased onto the state directory: - `storage.stateDir` / `CAIRN_STATE_DIR` when set (source `storage.stateDir`); - posix: `<storage.root>/.cairn` (source `storage.root`) — identical to today with the default root; - s3: unchanged `/data/.cairn` (source `default`); state documents are in the bucket anyway. - Explicit paths are kept. **Stay local by design:** `tusSpoolDir`, `peering.stagingDir` (cleanup via #826), and `bootstrap.json` (how Cairn finds the root). Follow the state dir: all state files, pictures, preview cache, audit log, marks ledger. - `<root>/.cairn` is already a reserved root (`internal/storage/reserved`), so it is invisible on every user surface. - **Upgrade:** `moveStateDir` moves state left on `/data/.cairn` once (files + avatars/spaceimg/audit/marks), #154 adopt-or-refuse per file; retired copies stay as `*.migrated`; scratch, bootstrap and foreign files untouched. - Startup log: `instance state directory (#821) dir=… from=…`. **Why (research):** Vaultwarden (`DATA_FOLDER`, everything derives), Gitea (`APP_DATA_PATH` from `WORK_PATH`; a default outside the mounted volume lost data, fixed by a breaking change "the only way … to avoid users losing their data accidently"), Nextcloud (appdata inside `datadirectory`, and the opposite demand #32270/#3034 for a deliberate split → our `stateDir`), MinIO (`.minio.sys` beside the data). **Tests:** `config` table test (default unchanged, moved root, stateDir wins, explicit paths kept, s3 untouched, look-alike prefix not rewritten); `moveStateDir` (moves state, retires old, leaves scratch/bootstrap/foreign files, idempotent, refuses on differing copies). Ran the binary with `storage.root=/tmp/…/root`: boots (previously it needed a writable `/data`), state lands in `root/.cairn`. **Docs:** deployment.md "Where state lives" + "Splitting state from files on purpose", upgrade note, refusal list, backups paragraph (also drops the stale "versioning delegated to snapshots"). CHANGELOG v0.6.311.
posix: state follows storage.root; storage.stateDir for a deliberate split (#821)
All checks were successful
ci / test-and-build (pull_request) Successful in 1m25s
1454e97d6b
- config.ResolveStateDir rebases every path still at its /data/.cairn
  default onto <root>/.cairn (posix) or storage.stateDir / CAIRN_STATE_DIR;
  s3 keeps the local default. Explicit paths kept; TUS spool and peering
  staging stay local (#826 handles their cleanup); bootstrap pointer untouched
- one-time move of state left on /data/.cairn (adopt-or-refuse, #154),
  incl. pictures, audit, marks
- startup log names the state directory and its source
- deployment.md: Where state lives, splitting on purpose, upgrade note,
  refusal list, backups (versions no longer delegated to snapshots)
- CHANGELOG v0.6.311
Cordy merged commit 2d7642a1df into main 2026-10-01 05:53:05 +00:00
Cordy deleted branch fix-821b 2026-10-01 05:53:07 +00:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Cordy/Cairn#827
No description provided.