Unraid Deployment

Opslag

Active state gebruikt directe SSD/NVMe poolpaden:

/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:

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:

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:

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)

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

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

# 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):

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.

5.1 KiB Raw Blame History