Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

docs/09_OPERATIONS/UNRAID_DEPLOYMENT.md

@@ -0,0 +1,138 @@
+# Unraid Deployment
+
+## Opslag
+
+Active state gebruikt directe SSD/NVMe poolpaden:
+
+```text
+/mnt/<pool>/appdata/ragcore/postgres
+/mnt/<pool>/appdata/ragcore/qdrant
+/mnt/<pool>/appdata/ragcore/blobs
+/mnt/<pool>/appdata/ragcore/parsed
+/mnt/<pool>/appdata/ragcore/tmp
+```
+
+Gebruik voor PostgreSQL/Qdrant **niet** `/mnt/pool/appdata/...`. Backupexports mogen naar `/mnt/pool/backups/ragcore`.
+
+## Deployment
+
+- Maak `.env` uit voorbeeld en genereer unieke secrets.
+- Zet `RAGCORE_STATE_ROOT` naar direct poolpad.
+- Start Compose; houd `models` profiel uit wanneer centrale Ollama bestaat.
+- Maak één dedicated extern Docker-netwerk voor Nginx Proxy Manager en RAGCore.
+- Configureer Nginx Proxy Manager naar `ragcore-app:8080` op dat netwerk.
+- Publiceer de app-hostpoort uitsluitend op `127.0.0.1`; stuur nooit bearer-tokens
+  rechtstreeks over een LAN-HTTP-poort.
+- Koppel Authentik/OIDC in productie.
+- Publiceer geen PostgreSQL/Qdrant/Ollamapoort.
+
+### Reverse-proxy trust boundary
+
+Productie accepteert `X-Forwarded-*` uitsluitend van de expliciet ingestelde
+proxy-IP/CIDR. Wildcardtrust (`*`, `0.0.0.0/0`, `::/0`) wordt bij startup
+geweigerd. Een dedicated netwerk voorkomt dat een willekeurige container binnen
+een breed gedeeld subnet als vertrouwde proxy kan optreden.
+
+Eenmalige netwerkinitialisatie voor de gedocumenteerde Unraid-topologie:
+
+```bash
+docker network create --driver bridge --subnet 172.30.50.0/29 ragcore-proxy
+docker network connect --ip 172.30.50.2 ragcore-proxy NginxProxyManager
+```
+
+Voeg aan `.env` toe:
+
+```dotenv
+RAGCORE_PUBLIC_BASE_URL=https://rag.example.com
+RAGCORE_TRUSTED_PROXY_IPS=172.30.50.2
+RAGCORE_PROXY_NETWORK=ragcore-proxy
+```
+
+De productie-Compose koppelt `app` met alias `ragcore-app` aan dit externe
+netwerk. Stel de Nginx Proxy Manager upstream in op scheme `http`, hostname
+`ragcore-app`, port `8080`. Controleer HTTPS vóór de oude upstream wordt
+verwijderd. De loopback-hostpoort blijft alleen voor lokale healthchecks en
+rollbackdiagnose beschikbaar. Vertrouw bij voorkeur uitsluitend het statische
+IP van Nginx Proxy Manager. Een CIDR is alleen correct wanneer elk adres in dat
+bereik een geautoriseerde proxy is; een Docker-netwerkgateway valt ook binnen
+het subnet en mag daarom niet impliciet forwardingheaders mogen aanleveren.
+
+## Preflight
+
+Beschikbare disk/RAM, filesystem, ownership UID 10001, klok/NTP, backupdoel, modelendpoint en reverse-proxy headers controleren:
+
+```bash
+python3 scripts/unraid_preflight.py \
+  --state-root /mnt/<pool>/appdata/ragcore \
+  --backup-dir /mnt/pool/backups/ragcore \
+  --ollama-url http://<ollama-host>:11434 \
+  --base-url https://ragcore.example.com
+```
+
+Blokkerende bevindingen (`[BLOCK]`, o.a. een actieve `/mnt/user`-status voor
+`--state-root`) stoppen de deploy; `[WARN]` is informatief (bijv. klok-sync
+niet vast te stellen buiten een Linux-host).
+
+## Operational runbook
+
+Alle commando's hieronder gaan uit van `compose.yaml` + `compose.production.yaml`
+samen; nooit `compose.test.yaml` of `compose.restore-test.yaml` in productie
+(die zijn uitsluitend voor lokale/testomgevingen).
+
+### Start (eerste deploy of na reboot)
+
+```bash
+cp .env.example .env   # eenmalig; vul echte secrets en RAGCORE_STATE_ROOT in
+python3 scripts/unraid_preflight.py --state-root /mnt/<pool>/appdata/ragcore --backup-dir /mnt/pool/backups/ragcore
+docker compose -f compose.yaml -f compose.production.yaml up -d
+python3 scripts/check_app_health.py --base-url https://rag.example.com
+```
+
+### Stop
+
+```bash
+docker compose -f compose.yaml -f compose.production.yaml stop
+```
+
+Gebruik `down` (in plaats van `stop`) alleen wanneer je ook de containers en
+het (interne) netwerk wilt verwijderen; volumes/bind mounts (dus alle data)
+blijven in beide gevallen ongemoeid tenzij `-v` wordt toegevoegd -- gebruik
+`-v` nooit in productie.
+
+### Upgrade
+
+```bash
+# 1. Backup vóór elke upgrade (zie runbooks/BACKUP.md)
+python3 scripts/backup.py --backup-root /mnt/pool/backups/ragcore
+
+# 2. Nieuwe image ophalen/bouwen en migreren
+git pull   # of: nieuwe release-ZIP uitpakken
+docker compose -f compose.yaml -f compose.production.yaml build app worker mcp
+docker compose -f compose.yaml -f compose.production.yaml run --rm app alembic upgrade head
+
+# 3. Rollend herstarten
+docker compose -f compose.yaml -f compose.production.yaml up -d
+python3 scripts/check_app_health.py --base-url https://rag.example.com
+```
+
+Zie `docs/09_OPERATIONS/UPGRADE_STRATEGY.md` voor het volledige beleid
+(o.a. backward-compatibele migraties, nooit in-place index-upgrades).
+
+### Rollback
+
+Applicatie-rollback (voorkeur, geen restore):
+
+```bash
+git checkout <vorige-release-tag-of-commit>   # of: vorige release-ZIP
+docker compose -f compose.yaml -f compose.production.yaml build app worker mcp
+docker compose -f compose.yaml -f compose.production.yaml up -d
+```
+
+Migraties zijn per beleid backward-compatible voor minstens één release, dus
+een applicatie-rollback tegen de nieuwere schema-versie werkt zonder
+`alembic downgrade`. Een volledige restore vanaf backup is het laatste
+redmiddel, niet de normale rollback-weg -- zie `runbooks/RESTORE.md`.
+
+Index-/profielactivatie-rollback (indien van toepassing) gaat via
+`/admin/profiles` (M4-07's `ProfileActivationService`), niet via deze
+Compose-commando's.