VacatureRadar/docs/operations/UNRAID_DEPLOYMENT.md

Unraid-deployment

Deze handleiding gebruikt docker-compose.unraid.yml als declaratieve bron van waarheid. Unraid-installaties verschillen in gebruikte Compose Manager, reverse proxy en shares; behoud de hieronder genoemde volumes, secrets en netwerkgrenzen ook wanneer de UI de services afzonderlijk aanmaakt.

Vooraf

Maak deze directories:

/mnt/user/appdata/vacatureradar/config
/mnt/user/appdata/vacatureradar/media
/mnt/user/appdata/vacatureradar/logs
/mnt/user/appdata/vacatureradar/postgres
/mnt/user/appdata/vacatureradar/redis
/mnt/user/appdata/vacatureradar/ollama       # alleen bij lokale AI
/mnt/user/backups/vacatureradar

Gebruik bij voorkeur een cache-backed appdata-share en neem die afzonderlijk in je back-upregime op. De PostgreSQL-datadir mag niet gelijktijdig door file-syncsoftware worden gemuteerd.

Imagekeuze

De Unraid-compose bevat bewust ghcr.io/CHANGE_ME/vacatureradar:latest. Codex kan code, Dockerfile en CI afwerken zonder registrycredentials, maar voor productie moet een van deze paden worden gekozen:

1. bouw lokaal op de Unraid-host en vervang image: door een vaste lokale tag;
2. publiceer vanuit CI naar een private registry en pin op een immutable digest;
3. gebruik build:, mits de gekozen Compose-plugin builds betrouwbaar ondersteunt.

Gebruik in productie geen zwevende latest zonder gecontroleerd rollbackpad.

Configuratiebestand

Kopieer of genereer .env naar:

De deploy-helper scripts/deploy_docker.sh vult ontbrekende sleutels op basis van veilige defaults. Zet voor publieke productie vooraf de gewenste variabelen:

/mnt/user/appdata/vacatureradar/config/.env
APP_HOST=jobs.example.be
APP_SCHEME=https
DJANGO_DEBUG=0
SESSION_COOKIE_SECURE=1
CSRF_COOKIE_SECURE=1
SECURE_SSL_REDIRECT=1

Gebruik daarna de helper (zie hieronder).

Beperk de bestandsrechten van .env tot de beheerder. Voeg geen secrets toe aan de ZIP, Git, screenshots of supportlogs.

Eerste uitrol

1. Controleer alle CHANGE_ME-waarden.
2. Gebruik de deploy-helper voor een snelle eerste start:

cd /app/VacatureRadar
APP_HOST=jobs.example.be APP_SCHEME=https DJANGO_DEBUG=0 \
SESSION_COOKIE_SECURE=1 CSRF_COOKIE_SECURE=1 SECURE_SSL_REDIRECT=1 \
bash scripts/deploy_docker.sh

3. Start eerst PostgreSQL en Redis.
4. Start web; de entrypoint voert migraties uit.
5. Start worker en scheduler.
6. Controleer GET /health/live/ en GET /health/ready/.
7. Voer eenmalig in de webcontainer uit:

python manage.py bootstrap_instance
python manage.py collectstatic --noinput

7. Meld lokaal aan en wijzig het bootstrapwachtwoord.
8. Activeer nog geen live bron of mailbox voordat bronbeleid, retentie en back-up zijn gecontroleerd.

Releaseverificatie en upgradepad

VR-117 voegt ./scripts/release_verify.sh toe als release-check met artifacts voor package, checksum, configdiff, sbom en upgrade/rollback. Het script bewaart:

• release-artifacts/<ts>/artifacts/release-smoke.json
• release-artifacts/<ts>/artifacts/smoke-restored-validate.json
• release-artifacts/<ts>/artifacts/upgrade-rollback.md
• release-artifacts/<ts>/artifacts/checksums.txt
• release-artifacts/<ts>/artifacts/config-diff.txt

De restorecontrole vergelijkt primaire en gerestoreerde modelcounts in beide smoke-rapporten.

Reverse proxy en TLS

Expose de applicatie niet rechtstreeks op internet. Plaats Nginx Proxy Manager, Traefik, Caddy of een gelijkwaardig beheerd reverse-proxyprofiel voor poort 1226. Vereisten:

• geldig TLS-certificaat;
• alleen HTTPS extern;
• X-Forwarded-Proto correct doorgeven;
• request-bodylimiet klein houden; er is geen algemene upload-API;
• optioneel extra access control/VPN voor persoonlijke installatie;
• geen publieke toegang tot PostgreSQL, Redis of Ollama.

Wanneer een proxy op hetzelfde Docker-netwerk draait, publiceer poort 1226 alleen intern. Wanneer Unraid routing een hostpoort vereist, beperk die via firewall/VLAN tot de proxy of het beheernetwerk.

Mailbox

Gebruik een aparte mailbox of alias, niet de hoofdmailbox. Begin met:

IMAP_ENABLED=0
IMAP_MARK_SEEN=0

Na een succesvolle fixture- en read-onlytest:

IMAP_ENABLED=1
IMAP_HOST=<host>
IMAP_USER=<account>
IMAP_PASSWORD=<app-password>
IMAP_MAILBOX=INBOX
IMAP_USE_SSL=1

Het account heeft alleen mailboxrechten nodig. Gebruik waar beschikbaar een app-password en schakel interactieve login op die mailbox niet uit zolang herstel nodig is.

Ollama

Ollama is optioneel. Start de composeprofile pas wanneer de deterministische kern goed werkt:

docker compose -f docker-compose.unraid.yml --profile ai up -d

Pin een modelnaam in OLLAMA_MODEL; zonder model blijft OLLAMA_ENABLED=0. Stel Ollama niet extern bloot. Modeloutput wordt als onbetrouwbare gestructureerde data behandeld en mag geen harde regel of sollicitatieactie uitvoeren.

Upgraden

1. Maak en verifieer een database- en configuratieback-up.
2. Lees CHANGELOG.md en de releaseartefacten.
3. Als de release nog niet geverifieerd is, voer ./scripts/release_verify.sh lokaal uit.
4. Pull/bouw de nieuwe immutable image.
5. Stop scheduler en worker, daarna web.
6. Start web en laat migraties uitvoeren.
7. Controleer health, login en release-smoke-rapport.
8. Start worker en scheduler.
9. Bewaar de vorige image/digest totdat één volledige schedulercyclus goed verliep.

Rollback

Bij een codefout zonder incompatibele migratie: pin de vorige image en herstart web/worker/scheduler. Bij een incompatibele datamigratie: stop alle schrijvers, herstel de vooraf gemaakte databaseback-up en gebruik de overeenkomende vorige image. Voer nooit een restore uit terwijl de worker of scheduler schrijft.

Productiechecklist

• alle CHANGE_ME-waarden verwijderd;
• debug uit en secure cookies aan;
• TLS en host/origin exact ingesteld;
• PostgreSQL/Redis/Ollama niet publiek;
• dagelijkse back-up plus periodieke hersteltest;
• aparte IMAP-mailbox met minimale rechten;
• bronpolicy per actieve bron op allow met reviewdatum;
• adminwachtwoord gewijzigd;
• healthmonitoring en vrije schijfruimtebewaking;
• retentiejob en logrotatie gecontroleerd.