Initial curated itworx-knowledge-hub source from 3b1751d0d9dee551aa6994eee0093704dc334817

docs/guides/operationele-runbooks-overzicht.md

@@ -0,0 +1,75 @@
+# Operationele runbooks — overzicht
+
+Deze gids wijst naar de bestaande, feitelijk geïmplementeerde runbook-onderwerpen
+(`docs/25-release-and-operations.md` "Operational runbooks required by 1.0") en
+beschrijft de twee onderwerpen die nog geen eigen gids hadden. Waar een onderwerp niet
+of nog niet volledig is geïmplementeerd, staat dat hier expliciet — nooit stilzwijgend
+verondersteld.
+
+| Onderwerp | Status | Waar |
+| --- | --- | --- |
+| Eerste implementatie | Geïmplementeerd en getest | `docs/23-deployment-unraid.md` "First deployment"; `docs/guides/eerste-installatie-en-aanmelden.md` |
+| Eigenaarherstel (wachtwoord) | Geïmplementeerd en getest | `docs/guides/eerste-installatie-en-aanmelden.md` (herstel-token) |
+| Back-up maken | Geïmplementeerd en getest | `docs/guides/back-ups-herstel-en-unraid-beheer.md` |
+| Schoon herstel | Geïmplementeerd en getest | `docs/guides/back-ups-herstel-en-unraid-beheer.md` |
+| Applicatie bijwerken | Geïmplementeerd en getest | `docs/23-deployment-unraid.md` "Updates"; schema-driftweigering (M7) |
+| Applicatie terugzetten (rollback) | Geïmplementeerd en getest | `docs/23-deployment-unraid.md` "Rollback"; zie ook onderstaande sectie |
+| PostgreSQL kleine update | Geïmplementeerd en getest | Onderstaande sectie (nieuw voor M8) |
+| PostgreSQL grote upgrade (rehearsal) | **Niet uitgevoerd** | Zie "Bekende beperkingen" hieronder |
+| Opslag-/integriteitsstoring | Geïmplementeerd en getest | Onderstaande sectie (nieuw voor M8) |
+| Import en rollback | Geïmplementeerd en getest | `docs/guides/bijlagen-en-leafwiki-import.md` |
+| Gecompromitteerd service-token | Geïmplementeerd en getest | `docs/guides/service-accounts-en-automatisering.md` (intrekken) |
+| Gegevensexport | **Niet geïmplementeerd** | Zie "Bekende beperkingen" hieronder |
+| LeafWiki-overstap (cutover) | Ontworpen, niet uitgevoerd tegen echte data | `docs/17-leafwiki-migration.md`; echte overstap is M9-scope |
+
+## PostgreSQL kleine update
+
+Kleine (minor) PostgreSQL-updates binnen dezelfde hoofdversie (18.x) zijn compatibel met
+hetzelfde datavolume:
+
+1. Bevestig een recente, geverifieerde back-up (`docs/guides/back-ups-herstel-en-unraid-beheer.md`).
+2. Werk de `postgres`-image-tag bij naar de nieuwe kleine versie in `docker-compose.yml`
+   (bijvoorbeeld `postgres:18.5-bookworm`).
+3. `docker compose pull db && docker compose up -d db` — het bestaande datavolume
+   (`knowledge-hub-db`) wordt hergebruikt; PostgreSQL werkt zelf bij bij het opstarten.
+4. Controleer `docker compose ps` (status `healthy`) en start daarna de applicatie
+   opnieuw op (`docker compose up -d app`).
+5. Controleer `GET /health/ready` en een geauthenticeerde `GET /api/v1/system/info`.
+
+Nooit een grote (major) versiesprong op deze manier uitvoeren — zie hieronder.
+
+## Opslag-/integriteitsstoring
+
+Wanneer `GET /health/ready` onbereikbaarheid van de database of een niet-beschrijfbaar
+opslagpad rapporteert (`DatabaseHealthCheck`/`StorageHealthCheck`, M7):
+
+1. Controleer `docker compose ps` en `docker logs itworx-knowledge-hub-db-1` /
+   `itworx-knowledge-hub-app-1` voor de onderliggende fout.
+2. Controleer of de onderliggende Unraid-schijf/-pool vol is of in fout-status staat
+   (buiten het bereik van de applicatie zelf — de applicatie draait immers met een
+   alleen-lezen hoofdbestandssysteem en kan de hostopslag niet zelf herstellen).
+3. Herstel de opslag/host-laag eerst; herstart pas daarna de containers.
+4. Als gegevensverlies of -corruptie wordt vermoed: **schrijf niets meer** naar de
+   database totdat een back-up is bevestigd. Herstel bij twijfel vanaf de laatst
+   geverifieerde back-up naar een schone doelomgeving
+   (`docs/guides/back-ups-herstel-en-unraid-beheer.md`) in plaats van de productie-
+   database rechtstreeks te herstellen met ad-hoc SQL
+   (`docs/25-release-and-operations.md` "Incident priorities": "Do not 'repair'
+   production data through undocumented ad hoc SQL").
+
+## Bekende beperkingen
+
+- **Gegevensexport is nog niet geïmplementeerd** als eindgebruikersfunctie. De enige
+  vorm van "export" die vandaag bestaat, is de back-up zelf
+  (`docs/guides/back-ups-herstel-en-unraid-beheer.md`), die het volledige datamodel
+  bevat maar niet bedoeld is als leesbaar exportformaat voor een individuele pagina of
+  project. Een gerichte exportfunctie (bijvoorbeeld Markdown-export per pagina/project)
+  is niet gepland vóór een toekomstige milestone met een expliciet acceptatiecriterium.
+- **De PostgreSQL major-upgrade-rehearsal is niet uitgevoerd.** Dit vereist een tweede,
+  oudere PostgreSQL-hoofdversie plus `pg_upgrade`- of dump/restore-oefening, wat buiten
+  de tijdsbox van dit release-traject valt en geen acuut risico vormt zolang de
+  applicatie op één vaste hoofdversie (18) blijft draaien. Voer deze oefening uit
+  vóórdat een major-upgrade daadwerkelijk wordt gepland.
+- **De echte LeafWiki-overstap** vereist de echte LeafWiki-momentopname en productie-
+  Unraid-omgeving van de gebruiker — een expliciete externe blokkade
+  (`CLAUDE.md` §3), uitgevoerd in M9 zodra beschikbaar.