stwaidele/dorfteich
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 22 Wiki Activity

[VS-NfD] Write the operations manual (installation, update, backup/restore, deletion, role separation) #229

New Issue
Closed
opened 2026-07-30 01:43:57 +02:00 by fable-5 · 4 comments
fable-5 commented 2026-07-30 01:43:57 +02:00
Collaborator
Copy Link

Plan reference: 20-massnahmenplan.md -> Phase 5
ADR: ADR 0019
Effort: L (4–5 AT)
Depends on: #193, #194, #221

Context

The operator has to run this without us, including on the day something
fails. Deletion and destruction is the chapter with the most VS-specific
weight.

Current state

  • Partial material: docs/operations/restore-runbook.md,
    deploy/stages.md, docs/architecture/operations.md,
    deploy/backup-basel.md, deploy/monitoring.md.
  • Gaps that must be closed by their issues before this can be truthful:
    pond purge (#193), orphan-file sweep (#194), offline update (#221).

Acceptance criteria

  • Installation including the airgap variant (referencing #218–#221).
  • Update and rollback, with the migration caveats from #221.
  • Backup and restore, including a rehearsed restore and the
    restriction on targets from #192.
  • Deletion and destruction: per content type, what deletion does, which
    copies it reaches (using the list from #228), how long residues
    persist, and how an instance is decommissioned.
  • Role separation: which tasks need Site-Admin, which need platform
    access, and what a Site-Admin can not do.
  • Every procedure has been executed at least once by its author, and
    says so.

Out of scope

Customer-specific operating concepts, and 24/7 support processes.

**Plan reference:** `20-massnahmenplan.md` -> Phase 5 **ADR:** ADR 0019 **Effort:** L (4–5 AT) **Depends on:** #193, #194, #221 ## Context The operator has to run this without us, including on the day something fails. Deletion and destruction is the chapter with the most VS-specific weight. ## Current state - Partial material: `docs/operations/restore-runbook.md`, `deploy/stages.md`, `docs/architecture/operations.md`, `deploy/backup-basel.md`, `deploy/monitoring.md`. - Gaps that must be closed by their issues before this can be truthful: pond purge (#193), orphan-file sweep (#194), offline update (#221). ## Acceptance criteria - [ ] Installation including the airgap variant (referencing #218–#221). - [ ] Update and rollback, with the migration caveats from #221. - [ ] Backup and restore, including a rehearsed restore and the restriction on targets from #192. - [ ] Deletion and destruction: per content type, what deletion does, which copies it reaches (using the list from #228), how long residues persist, and how an instance is decommissioned. - [ ] Role separation: which tasks need Site-Admin, which need platform access, and what a Site-Admin can **not** do. - [ ] Every procedure has been executed at least once by its author, and says so. ## Out of scope Customer-specific operating concepts, and 24/7 support processes.
fable-5 added this to the M30 — VS-NfD: compliance documentation milestone 2026-07-30 01:43:57 +02:00
fable-5 added the
effort:L
area:docs
vs-nfd
 labels 2026-07-30 01:43:57 +02:00
fable-5 commented 2026-07-30 22:20:56 +02:00
Author
Collaborator
Copy Link

For the deletion-and-destruction chapter, three additions from M24:

  • conversion-payload-prune (daily, #233): input/result bytes of finished (succeeded/failed) import/export conversion jobs are nulled after conversion.payloadRetentionDays (default 30); the row survives for status/audit. PENDING/RUNNING rows are never touched. Migration backfilled already-finished jobs past the default period.
  • mail-outbox-retention (daily, #234): SENT rows (by sentAt) and permanently FAILED rows (by nextAttemptAt) are deleted after mail.outboxRetentionDays (default 30). PENDING rows belong to the retry loop and are never deleted here.
  • page_links residue (#235): rows pointing at a purged page are KEPT by decision (index of text that remains in the linking page's own content; deleting the row removes nothing the system still shows and would break phantom-link re-resolution) - the chapter should name this so an operator can answer for it. Reasoning: operations.md purge section; residual-risk record on #231.
For the deletion-and-destruction chapter, three additions from M24: - conversion-payload-prune (daily, #233): input/result bytes of finished (succeeded/failed) import/export conversion jobs are nulled after conversion.payloadRetentionDays (default 30); the row survives for status/audit. PENDING/RUNNING rows are never touched. Migration backfilled already-finished jobs past the default period. - mail-outbox-retention (daily, #234): SENT rows (by sentAt) and permanently FAILED rows (by nextAttemptAt) are deleted after mail.outboxRetentionDays (default 30). PENDING rows belong to the retry loop and are never deleted here. - page_links residue (#235): rows pointing at a purged page are KEPT by decision (index of text that remains in the linking page's own content; deleting the row removes nothing the system still shows and would break phantom-link re-resolution) - the chapter should name this so an operator can answer for it. Reasoning: operations.md purge section; residual-risk record on #231.
fable-5 commented 2026-07-31 04:52:27 +02:00
Author
Collaborator
Copy Link

Addition for the operator documentation from #199 (attachment integrity, PR #259): every download re-hashes the stored attachment before serving and fails closed with attachment_integrity_failure (HTTP 500) on mismatch; the audit trail records file.integrity_failed with both hashes (expected = stored at upload, actual = computed now). Operator response: treat the object as tampered or corrupt, restore the affected file from a backup set (restore runbook), then re-download to confirm; the audit entry carries the hashes for the report. Rows predating the column are hashed by the nightly backfill riding the orphan-file-sweep job; a file that cannot be read is logged and retried nightly - a persistent unreadable report means the bytes are gone and the restore path above applies. Full behaviour: security.md, Content & upload security.

Addition for the operator documentation from #199 (attachment integrity, PR #259): every download re-hashes the stored attachment before serving and fails closed with attachment_integrity_failure (HTTP 500) on mismatch; the audit trail records file.integrity_failed with both hashes (expected = stored at upload, actual = computed now). Operator response: treat the object as tampered or corrupt, restore the affected file from a backup set (restore runbook), then re-download to confirm; the audit entry carries the hashes for the report. Rows predating the column are hashed by the nightly backfill riding the orphan-file-sweep job; a file that cannot be read is logged and retried nightly - a persistent unreadable report means the bytes are gone and the restore path above applies. Full behaviour: security.md, Content & upload security.
fable-5 commented 2026-07-31 05:29:14 +02:00
Author
Collaborator
Copy Link

Addition for the operator documentation from #203 (PR #262): all third-party deploy images are digest-pinned (name:tag@sha256) in deploy/compose/docker-compose.yml; a CI step rejects any unpinned third-party reference. Updating a digest: docker buildx imagetools inspect name:tag resolves the manifest-list digest; change the compose reference, let CI confirm, then roll the same change out by hand to /srv/DOCKER/dorfteich-{test,int,prod}/docker-compose.yml (CD does not sync stage composes) and verify via docker inspect after the next pull/up. Full procedure: deploy/stages.md section 5a.

Addition for the operator documentation from #203 (PR #262): all third-party deploy images are digest-pinned (name:tag@sha256) in deploy/compose/docker-compose.yml; a CI step rejects any unpinned third-party reference. Updating a digest: docker buildx imagetools inspect <name:tag> resolves the manifest-list digest; change the compose reference, let CI confirm, then roll the same change out by hand to /srv/DOCKER/dorfteich-{test,int,prod}/docker-compose.yml (CD does not sync stage composes) and verify via docker inspect after the next pull/up. Full procedure: deploy/stages.md section 5a.
fable-5 commented 2026-07-31 10:57:16 +02:00
Author
Collaborator
Copy Link

Done in commit 040f3fb (PR #274, CI run 580 green, fast-forward merged on Stefan's standing merge instruction).

Evidence: docs/vs-nfd/70-betriebshandbuch.md - installation as actually run on the stages; airgap variant explicitly pending #218-#221 (M28) with existing groundwork named; update/rollback incl. the no-down-migrations caveat; backup/restore with the deploy-level target allowlist (#192) and the REHEARSED monthly restore drill (evidence: logs on #98); complete scheduler-job table (9 jobs, cadences verified against code); deletion-and-destruction per content type on the #228 copy list incl. immediate-destruction path and decommissioning; role separation with the explicit Site-Admin limits and the honest read-bypass note (residual risk R-09). Every procedure carries its evidence level - erprobt / Mechanik vorhanden, nicht geprobt / offen - nothing claimed above what was executed (rollback and manual backup-chain destruction are marked NOT rehearsed).

Done in commit 040f3fb (PR #274, CI run 580 green, fast-forward merged on Stefan's standing merge instruction). Evidence: docs/vs-nfd/70-betriebshandbuch.md - installation as actually run on the stages; airgap variant explicitly pending #218-#221 (M28) with existing groundwork named; update/rollback incl. the no-down-migrations caveat; backup/restore with the deploy-level target allowlist (#192) and the REHEARSED monthly restore drill (evidence: logs on #98); complete scheduler-job table (9 jobs, cadences verified against code); deletion-and-destruction per content type on the #228 copy list incl. immediate-destruction path and decommissioning; role separation with the explicit Site-Admin limits and the honest read-bypass note (residual risk R-09). Every procedure carries its evidence level - erprobt / Mechanik vorhanden, nicht geprobt / offen - nothing claimed above what was executed (rollback and manual backup-chain destruction are marked NOT rehearsed).
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels   
area:auth

   
area:docs

   
area:export

   
area:ops

   
area:storage

   
area:supply-chain

   
auth

Authentication, permissions, quotas

  
backend

API server (apps/api)

  
blocked

Blocked on external dependency/infrastructure

  
collab

Collaboration server (apps/collab)

  
deployment

Docker, CI/CD, hosting

  
docs

Documentation

  
effort:L

   
effort:M

   
effort:S

   
frontend

SPA (apps/web)

  
plugins

Plugin system and SDK

  
qa

Tests, fixtures, e2e

  
vs-nfd

   
vs-nfd:blocker
No Label
area:auth
area:docs
area:export
area:ops
area:storage
area:supply-chain
auth
backend
blocked
collab
deployment
docs
effort:L
effort:M
effort:S
frontend
plugins
qa
vs-nfd
vs-nfd:blocker
Milestone
Clear milestone
No items
No Milestone
M30 — VS-NfD: compliance documentation
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
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: stwaidele/dorfteich#229
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?