Docs handbook: accumulate guides/FAQ/deployment docs as source material for swisscairn.ch #109

Closed
opened 2026-08-04 12:07:07 +00:00 by Cordy · 4 comments
Owner

Nikola, 2026-08-04: "slowly by now guides, FAQs, deployment docs and anything that can be documented could be written somewhere to then be later used for swisscairn.ch."

Home: docs/handbook/ in this repo — versioned with the code it documents, reviewed like code, and later transformed into the swisscairn.ch docs site (the v0.6 "Public launch" milestone already includes the docs site; this issue is the content pipeline feeding it).

Seeded today (from the v0.3.2x work, where the knowledge is freshest):

  • index.md — handbook purpose + map
  • encryption.md — custody modes (keycloak-profile / openbao / deployment), recovery model, domain separation, post-quantum incl. the migration guide (#28)
  • spaces.md — self-service spaces, roles, member management, shared trash, live group resolution
  • licensing-faq.md — free tier, keys, check-in, refresh, labels vs org, seat semantics, air-gapped caveat (#91)
  • deployment.md — config reference walk-through, storage drivers, auth modes, Helm chart pointers

Working rules:

  • Every shipped feature that changes admin or user behavior adds/updates a handbook page in the same release cycle (same discipline as the changelog).
  • Handbook text is written product-neutral (no homelab IPs/names) so it can be lifted to swisscairn.ch without rewrites; homelab specifics stay in the Forgejo wikis.
  • Existing deep docs (ARCHITECTURE.md, ENCRYPTION-COMPARISON.md, docs/PUBLIC-SECTOR.md) stay canonical for design; the handbook is the operator/user-facing layer on top.

Backlog (fill as we go): WebDAV client setup (Finder/rclone/Cyberduck/Windows once #2 lands), OIDC/Keycloak setup guide, LDAP/AD setup guide, backup & recovery runbook (age -d sovereignty drill), quotas/retention/holds admin guide, troubleshooting FAQ, peering guide once v0.5 ships.

Nikola, 2026-08-04: "slowly by now guides, FAQs, deployment docs and anything that can be documented could be written somewhere to then be later used for swisscairn.ch." **Home:** `docs/handbook/` in this repo — versioned with the code it documents, reviewed like code, and later transformed into the swisscairn.ch docs site (the v0.6 "Public launch" milestone already includes the docs site; this issue is the content pipeline feeding it). **Seeded today** (from the v0.3.2x work, where the knowledge is freshest): - `index.md` — handbook purpose + map - `encryption.md` — custody modes (keycloak-profile / openbao / deployment), recovery model, domain separation, post-quantum incl. the migration guide (#28) - `spaces.md` — self-service spaces, roles, member management, shared trash, live group resolution - `licensing-faq.md` — free tier, keys, check-in, refresh, labels vs org, seat semantics, air-gapped caveat (#91) - `deployment.md` — config reference walk-through, storage drivers, auth modes, Helm chart pointers **Working rules:** - Every shipped feature that changes admin or user behavior adds/updates a handbook page in the same release cycle (same discipline as the changelog). - Handbook text is written product-neutral (no homelab IPs/names) so it can be lifted to swisscairn.ch without rewrites; homelab specifics stay in the Forgejo wikis. - Existing deep docs (`ARCHITECTURE.md`, `ENCRYPTION-COMPARISON.md`, `docs/PUBLIC-SECTOR.md`) stay canonical for design; the handbook is the operator/user-facing layer on top. **Backlog (fill as we go):** WebDAV client setup (Finder/rclone/Cyberduck/Windows once #2 lands), OIDC/Keycloak setup guide, LDAP/AD setup guide, backup & recovery runbook (age -d sovereignty drill), quotas/retention/holds admin guide, troubleshooting FAQ, peering guide once v0.5 ships.
Cordy added this to the v1.0 - Go live milestone 2026-08-04 12:07:07 +00:00
Author
Owner

Triage: autonomous (drafting; your steer on priority order). Draft docs/handbook/ pages as source for swisscairn.ch: deployment, config reference (now that the config surface is well-mapped), upgrade (CHANGELOG-first rule), encryption/custody model, quotas, backup story. First step: outline + deployment.md + config-reference.md, then iterate. Content the site (#26) lifts later.

**Triage: autonomous (drafting; your steer on priority order).** Draft `docs/handbook/` pages as source for swisscairn.ch: deployment, config reference (now that the config surface is well-mapped), upgrade (CHANGELOG-first rule), encryption/custody model, quotas, backup story. First step: outline + `deployment.md` + `config-reference.md`, then iterate. Content the site (#26) lifts later.
Cordy referenced this issue from a commit 2026-08-12 22:08:28 +00:00
Author
Owner

Added admin-policy.md (PR #205) — the admin Settings policies, all persisted in the state-backend: storage quotas (per-user + instance, #178), retention (#63), auto-purge (#77), legal holds (#63), and audit logging as a runtime toggle (#186). This clears "quotas/retention/holds admin guide" from the backlog and documents the v0.6.14–v0.6.16 work while it's fresh.

Confirmed the existing pages already cover their scope well — notably encryption.md already documents the #108 per-instance separation workaround (classical-only instanceSeed; "one hybrid identity per instance" for PQ) and the PQ migration checklist, so nothing to add there.

Remaining backlog (unchanged): WebDAV client setup (Finder/rclone/Cyberduck/Explorer), OIDC and LDAP/AD setup guides, backup & recovery runbook, troubleshooting FAQ. A full pre-launch reconciliation pass is tracked separately for v0.8.

Added **`admin-policy.md`** (PR #205) — the admin Settings policies, all persisted in the state-backend: storage quotas (per-user + instance, #178), retention (#63), auto-purge (#77), legal holds (#63), and audit logging as a runtime toggle (#186). This clears "quotas/retention/holds admin guide" from the backlog and documents the v0.6.14–v0.6.16 work while it's fresh. Confirmed the existing pages already cover their scope well — notably `encryption.md` already documents the #108 per-instance separation workaround (classical-only `instanceSeed`; "one hybrid identity per instance" for PQ) and the PQ migration checklist, so nothing to add there. **Remaining backlog** (unchanged): WebDAV client setup (Finder/rclone/Cyberduck/Explorer), OIDC and LDAP/AD setup guides, backup & recovery runbook, troubleshooting FAQ. A full pre-launch reconciliation pass is tracked separately for v0.8.
Author
Owner

Follow-up parked here from #350 (Encryption & keys page).

The Recovery tab ends with a hint pointing at the rotation procedure:

Full procedure: see Rotating the recovery identity in docs/handbook/encryption.md. It needs a restart, which signs everyone out.

That is a path, not a link, deliberately: the docs site is still preview-gated, so a real anchor would 404 for every operator until this issue lands. A dead link in the admin panel is worse than a path someone can follow in the repo or the image.

When the handbook content is lifted onto the site, convert it: the i18n key is encRotateHint in web/static/index.html, and the target anchor is #rotating-the-recovery-identity.

Worth checking at the same time whether other admin copy names doc paths the same way — this is unlikely to be the only one, and they should all become links in one pass rather than drifting apart.

**Follow-up parked here from #350 (Encryption & keys page).** The Recovery tab ends with a hint pointing at the rotation procedure: > Full procedure: see *Rotating the recovery identity* in `docs/handbook/encryption.md`. It needs a restart, which signs everyone out. That is a **path, not a link**, deliberately: the docs site is still preview-gated, so a real anchor would 404 for every operator until this issue lands. A dead link in the admin panel is worse than a path someone can follow in the repo or the image. When the handbook content is lifted onto the site, convert it: the i18n key is `encRotateHint` in `web/static/index.html`, and the target anchor is `#rotating-the-recovery-identity`. Worth checking at the same time whether other admin copy names doc paths the same way — this is unlikely to be the only one, and they should all become links in one pass rather than drifting apart.
Author
Owner

Closing as superseded by #206, which is this issue's closeout. The remaining backlog (backup runbook, troubleshooting FAQ, encRotateHint doc links) is moved there.

Closing as superseded by #206, which is this issue's closeout. The remaining backlog (backup runbook, troubleshooting FAQ, `encRotateHint` doc links) is moved there.
Cordy closed this issue 2026-10-26 23:43:10 +00:00
Sign in to join this conversation.
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#109
No description provided.