76 lines
4.9 KiB
Markdown
76 lines
4.9 KiB
Markdown
# 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.
|