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