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