From b5e8ae1820debf86b7c814d3693e9e146d1f7a72 Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Mon, 27 Jul 2026 13:11:47 +0200 Subject: [PATCH] Voeg productie-nginx-voorbeeldconfiguratie toe voor de reverse-proxy-Pi MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit production-nginx.conf.example (vóór certbot) en production-nginx.conf.post-certbot.example (referentie, na certbot) dekken alléén de react-frontend-site op slpsoftware.nl/www.slpsoftware.nl; de mail/iRedAdmin-proxying die op de daadwerkelijke productieserver ook op dit domein draait valt buiten de scope van deze feature en is bewust weggelaten. Bevat de acme-challenge location in het 443-blok (niet het poort-80-blok) en de sentry-tunnel-proxy, analoog aan de testomgeving- configuratie. Documentatie in deployment-plan.md en deployment-instructions.md bijgewerkt met productie-nginx-setupstappen. Co-Authored-By: Claude Sonnet 5 --- .../deployment/deployment-instructions.md | 13 +++- .../operations/deployment/deployment-plan.md | 4 +- .../nginx/production-nginx.conf.example | 55 +++++++++++++++ ...production-nginx.conf.post-certbot.example | 69 +++++++++++++++++++ 4 files changed, 136 insertions(+), 5 deletions(-) create mode 100644 aidlc-docs/features/react-frontend/operations/deployment/nginx/production-nginx.conf.example create mode 100644 aidlc-docs/features/react-frontend/operations/deployment/nginx/production-nginx.conf.post-certbot.example diff --git a/aidlc-docs/features/react-frontend/operations/deployment/deployment-instructions.md b/aidlc-docs/features/react-frontend/operations/deployment/deployment-instructions.md index 175a6a3..3e43aac 100644 --- a/aidlc-docs/features/react-frontend/operations/deployment/deployment-instructions.md +++ b/aidlc-docs/features/react-frontend/operations/deployment/deployment-instructions.md @@ -47,14 +47,21 @@ Dit vervangt het eerder hardcoded `DEPLOY_PATH` in het `env:`-blok van `continuo ## Eenmalige Setup — Domeinnaam & DNS - **Test**: `test.slpsoftware.nl` → moet als DNS A-record wijzen naar het publieke IP van de reverse-proxy-Pi. -- **Productie** (domein al bekend, nginx/SSL-configuratie op de Pi's moet nog opgezet worden): `slpsoftware.nl` (en `www.slpsoftware.nl`) → zelfde reverse-proxy-Pi. De deploy-pipeline zelf ondersteunt productie al (zie hieronder); wat nog ontbreekt is de nginx/SSL-configuratie en het aanmaken van de webroot-map op de Pi's, analoog aan de teststappen hieronder. +- **Productie** (domein al bekend, nginx/SSL-configuratie op de Pi's moet nog opgezet worden voor de react-frontend): `slpsoftware.nl` (en `www.slpsoftware.nl`) → zelfde reverse-proxy-Pi. De deploy-pipeline zelf ondersteunt productie al (zie hieronder); wat nog ontbreekt is de webroot-map op de webserver-Pi, analoog aan de teststappen hieronder. ## Eenmalige Setup — nginx & SSL op de Raspberry Pi's +### Test 1. Kopieer `operations/deployment/nginx/webserver-nginx.conf.example` naar `/etc/nginx/sites-available/` op de webserver-Pi, maak een symlink in `sites-enabled/`, en herlaad nginx. Dit bestand is de daadwerkelijk in gebruik zijnde configuratie (`server_name test.slpsoftware.nl`, luistert op poort 80, serveert vanaf `/mnt/storage1/www/html/test/slpsoftware`). 2. Kopieer `operations/deployment/nginx/reverse-proxy-nginx.conf.example` naar `/etc/nginx/sites-available/slpsoftware-test.conf` op de reverse-proxy-Pi, maak een symlink in `sites-enabled/`, en herlaad nginx. Dit is de versie van vóór certbot (alleen poort 80, geen SSL), met `server_name test.slpsoftware.nl`. 3. Vraag op de reverse-proxy-Pi een SSL-certificaat aan met certbot (Let's Encrypt), nadat het DNS-record klopt: `sudo certbot --nginx -d test.slpsoftware.nl`. Certbot herschrijft dit bestand automatisch met de HTTPS-configuratie en de HTTP→HTTPS-redirect — zie `operations/deployment/nginx/reverse-proxy-nginx.conf.post-certbot.example` voor hoe het er dan uitziet (referentie, niet zelf kopiëren). 4. Zorg dat de map `/mnt/storage1/www/html/test/slpsoftware` bestaat op de webserver-Pi en schrijfbaar is voor de gebruiker `webadmin` (bijv. `sudo mkdir -p /mnt/storage1/www/html/test/slpsoftware && sudo chown webadmin:webadmin /mnt/storage1/www/html/test/slpsoftware`). +### Productie +De reverse-proxy-Pi bedient op `slpsoftware.nl`/`www.slpsoftware.nl` in werkelijkheid meer dan alleen deze react-frontend-site (o.a. mail/iRedAdmin-proxying naar een aparte host) — dat valt buiten de scope van deze feature. De onderstaande voorbeeldbestanden dekken alléén het react-frontend-gedeelte: +1. Kopieer `operations/deployment/nginx/production-nginx.conf.example` naar `/etc/nginx/sites-available/slpsoftware.conf` op de reverse-proxy-Pi (of voeg het `location`/`server`-gedeelte toe aan een bestaand bestand als daar al andere server-blocks voor dit domein in staan), maak een symlink in `sites-enabled/`, en herlaad nginx. Dit is de versie van vóór certbot (alleen poort 80, geen SSL). +2. Vraag op de reverse-proxy-Pi een SSL-certificaat aan met certbot, nadat de DNS-records kloppen: `sudo certbot --nginx -d slpsoftware.nl -d www.slpsoftware.nl`. Certbot herschrijft dit bestand automatisch — zie `operations/deployment/nginx/production-nginx.conf.post-certbot.example` voor hoe het er dan uitziet (referentie, niet zelf kopiëren). Let op: de acme-challenge location hoort in het 443-blok, niet in het losse poort-80-blok — zie de toelichting in dat referentiebestand. +3. Zorg dat de productie-webroot-map bestaat op de webserver-Pi en schrijfbaar is voor `webadmin` (bijv. `sudo mkdir -p /mnt/storage1/www/html/slpsoftware && sudo chown webadmin:webadmin /mnt/storage1/www/html/slpsoftware`), analoog aan stap 4 van de testomgeving. + > **Waarom `deploy_path` en de nginx `root` niet hetzelfde pad zijn**: de pipeline uploadt via SCP naar `deploy_path` = `/html/test/slpsoftware` (de waarde van de Gitea variable `DEPLOY_PATH_TEST`, ingelezen via `env.DEPLOY_PATH` in `continuous_integration.yaml`), terwijl de nginx `root` in `webserver-nginx.conf.example` het volledige pad `/mnt/storage1/www/html/test/slpsoftware` is. Dit is geen fout of inconsistentie: de SSH/SCP-gebruiker (`webadmin`) heeft `/mnt/storage1/www` als root (vergelijkbaar met een FTP-chroot), dus vanuit het perspectief van deze gebruiker is `/html/test/slpsoftware` het juiste (relatieve) pad, terwijl dat op het bestandssysteem van de Pi zelf overeenkomt met het volledige pad `/mnt/storage1/www/html/test/slpsoftware` dat nginx als `root` gebruikt. Kortom: `deploy_path` (`/html/test/slpsoftware`) + de root van de `webadmin`-gebruiker (`/mnt/storage1/www`) = de nginx `root` (`/mnt/storage1/www/html/test/slpsoftware`). ## How to Deploy to Test @@ -77,7 +84,7 @@ Productie deployt **nooit** automatisch bij een push naar `master` — alleen vi Vereist eenmalig vooraf: - De Gitea-variable `DEPLOY_PATH_PRODUCTION` (zie boven). - De Gitea-variable `VITE_UMAMI_WEBSITE_ID_PRODUCTION` (zie `umami-setup.md` stap 4/5) — zónder deze wordt productieverkeer per ongeluk meegeteld bij de teststatistieken. -- De productie-nginx/SSL-configuratie + webroot-map op de Pi's (zie "Eenmalige Setup — Domeinnaam & DNS"). +- De productie-nginx/SSL-configuratie + webroot-map op de Pi's (zie "Eenmalige Setup — nginx & SSL op de Raspberry Pi's → Productie"). ## Verifying a Deployment 1. Bevestig dat de Gitea Actions run succesvol is (alle relevante jobs groen — `deploy-test` altijd, `build-production`/`deploy-production` alleen als je `deploy_production` had aangevinkt). @@ -85,5 +92,5 @@ Vereist eenmalig vooraf: ## Future Work - **Van wachtwoord naar SSH-key**: vervang `sshpass -p "${{ secrets.PI_MAIN_PASSWORD }}" scp ...` in `deploy.yaml` door een `scp`-commando met `-i ` (een nieuwe secret `PI_MAIN_SSH_KEY` die je eerst als bestand wegschrijft in de run-stap), en zet de bijbehorende public key in `~/.ssh/authorized_keys` van de `webadmin`-gebruiker op de webserver-Pi. Verwijder daarna het wachtwoord-secret. -- **Productie nginx/SSL-configuratie**: de deploy-pipeline ondersteunt productie al (`build-production`/`deploy-production`), maar er is nog geen productie-nginx-voorbeeldconfiguratie — deze is op verzoek van de gebruiker verwijderd totdat er een goed-werkende versie is, en kan later opnieuw opgebouwd worden naar analogie van `nginx/webserver-nginx.conf.example` en `nginx/reverse-proxy-nginx.conf.example`, met domein `slpsoftware.nl`. +- **Webserver-Pi-vhost voor productie**: er is nog geen `webserver-nginx.conf.example`-tegenhanger voor productie (de vhost op de webserver-Pi zelf die `slpsoftware.nl` serveert vanaf de productie-webroot). Bouw die op naar analogie van `nginx/webserver-nginx.conf.example`, met `server_name slpsoftware.nl www.slpsoftware.nl` en de productie-webroot als `root`. - **Apart productie-Sentry-project**: `build-production` gebruikt momenteel dezelfde `VITE_SENTRY_DSN` als de testbuild (Umami heeft al aparte website-ID's per omgeving, zie `umami-setup.md`). Overweeg dit te splitsen zodra test- en productie-events niet meer door elkaar gemengd mogen worden in hetzelfde Sentry-project. diff --git a/aidlc-docs/features/react-frontend/operations/deployment/deployment-plan.md b/aidlc-docs/features/react-frontend/operations/deployment/deployment-plan.md index 82400ed..6eebfd4 100644 --- a/aidlc-docs/features/react-frontend/operations/deployment/deployment-plan.md +++ b/aidlc-docs/features/react-frontend/operations/deployment/deployment-plan.md @@ -17,7 +17,7 @@ Sinds deze stap is er een echte, geautomatiseerde upload naar een **testomgeving ## Environments - **Test** (geautomatiseerd, altijd): zoals hierboven beschreven. Draait automatisch bij elke merge naar `master` en bij elke handmatige `workflow_dispatch`-run. Domeinnaam: `test.slpsoftware.nl` (SSL via certbot op de reverse-proxy-Pi). -- **Productie** (geautomatiseerd, opt-in): via een eigen `build-production`- en `deploy-production`-job in `continuous_integration.yaml`, die `deploy.yaml` aanroepen met `environment: production`. In tegenstelling tot de testdeploy draait dit **niet** automatisch bij een push naar `master` — alleen wanneer je de workflow handmatig start via `workflow_dispatch` mét het `deploy_production`-vinkje aangevinkt. Dit is bewust: zo kan niemand per ongeluk productie deployen door simpelweg naar `master` te pushen. Reden voor een aparte `build-production`-job (in plaats van hetzelfde artifact als de testbuild te hergebruiken): `VITE_APP_ENV` is een build-time Vite-variabele, dus één bundel kan niet tegelijk als `test` én `production` getagd zijn in Sentry/analytics. Domeinnaam: `slpsoftware.nl` (SSL eveneens via certbot). Er is (nog) geen productie-nginx-voorbeeldconfiguratie; deze is op verzoek verwijderd totdat er een goed-werkende, foutloze versie is, en kan later opnieuw opgebouwd worden naar analogie van de testomgeving-configuraties. Vereist eenmalig de Gitea-variable `DEPLOY_PATH_PRODUCTION` (zie `deployment-instructions.md`) — zonder deze faalt de upload. +- **Productie** (geautomatiseerd, opt-in): via een eigen `build-production`- en `deploy-production`-job in `continuous_integration.yaml`, die `deploy.yaml` aanroepen met `environment: production`. In tegenstelling tot de testdeploy draait dit **niet** automatisch bij een push naar `master` — alleen wanneer je de workflow handmatig start via `workflow_dispatch` mét het `deploy_production`-vinkje aangevinkt. Dit is bewust: zo kan niemand per ongeluk productie deployen door simpelweg naar `master` te pushen. Reden voor een aparte `build-production`-job (in plaats van hetzelfde artifact als de testbuild te hergebruiken): `VITE_APP_ENV` is een build-time Vite-variabele, dus één bundel kan niet tegelijk als `test` én `production` getagd zijn in Sentry/analytics. Domeinnaam: `slpsoftware.nl` (SSL eveneens via certbot). Productie-nginx-voorbeeldconfiguratie: `nginx/production-nginx.conf.example` (vóór certbot) en `nginx/production-nginx.conf.post-certbot.example` (referentie, hoe het bestand er na certbot uitziet) — dekt alléén de react-frontend-site; de daadwerkelijke productieserver regelt op hetzelfde domein ook mail/iRedAdmin-proxying, wat buiten de scope van deze feature valt. Vereist eenmalig de Gitea-variable `DEPLOY_PATH_PRODUCTION` (zie `deployment-instructions.md`) — zonder deze faalt de upload. ## Automation Level Volledig geautomatiseerd voor de testomgeving: build, test, lint én upload naar de test-Pi gebeuren zonder handmatige tussenstap, zodra er gemerged wordt naar `master` (of handmatig getriggerd wordt). Productie is ook geautomatiseerd, maar alleen als bewuste, expliciete actie (handmatige `workflow_dispatch` met het `deploy_production`-vinkje) — nooit automatisch bij een push. @@ -37,7 +37,7 @@ Deze secrets heten bewust `PI_MAIN_*` in plaats van `PI_TEST_*`: alle webhosts g Dit is bewust wachtwoord-authenticatie (voor nu, zoals gekozen), zodat de testomgeving snel werkend is. Zie "Future Work" in `deployment-instructions.md` voor de overstap naar SSH-key-authenticatie. ## Resolved Item — Productie-deploy Geautomatiseerd -`continuous_integration.yaml` bevat nu een `build-production`- en `deploy-production`-job, alleen actief bij een handmatige `workflow_dispatch`-run met het `deploy_production`-vinkje aangevinkt (zie "Environments" hierboven). Aangezien de webhost (Pi Main) dezelfde blijft als de testomgeving, worden de bestaande `PI_MAIN_*` secrets hergebruikt — pas dit pas aan naar omgeving-specifieke secrets als productie daadwerkelijk op een andere host komt. Domeinnaam (`slpsoftware.nl`) en SSL-aanpak (certbot/Let's Encrypt op de reverse-proxy-Pi) liggen al vast; er is bewust (nog) geen productie-nginx-voorbeeldconfiguratie, deze wordt later opnieuw opgebouwd zodra er een goed-werkende, foutloze versie is. **Voordat dit voor het eerst gebruikt wordt**, moet de Gitea-variable `DEPLOY_PATH_PRODUCTION` nog worden aangemaakt (zie `deployment-instructions.md`) — zonder deze faalt de upload. +`continuous_integration.yaml` bevat nu een `build-production`- en `deploy-production`-job, alleen actief bij een handmatige `workflow_dispatch`-run met het `deploy_production`-vinkje aangevinkt (zie "Environments" hierboven). Aangezien de webhost (Pi Main) dezelfde blijft als de testomgeving, worden de bestaande `PI_MAIN_*` secrets hergebruikt — pas dit pas aan naar omgeving-specifieke secrets als productie daadwerkelijk op een andere host komt. Domeinnaam (`slpsoftware.nl`) en SSL-aanpak (certbot/Let's Encrypt op de reverse-proxy-Pi) liggen al vast; zie `nginx/production-nginx.conf.example` / `nginx/production-nginx.conf.post-certbot.example` voor de voorbeeldconfiguratie (react-frontend-only, geen mail/iRedAdmin). **Voordat dit voor het eerst gebruikt wordt**, moet de Gitea-variable `DEPLOY_PATH_PRODUCTION` nog worden aangemaakt (zie `deployment-instructions.md`) — zonder deze faalt de upload. ## Verified Build Prerequisite Dit plan bouwt voort op de Build and Test-stage (`construction/build-and-test/build-and-test-summary.md`): `pnpm run build` produceert een statische `dist/`-bundel zonder server-side vereisten, geschikt om direct door nginx geserveerd te worden. diff --git a/aidlc-docs/features/react-frontend/operations/deployment/nginx/production-nginx.conf.example b/aidlc-docs/features/react-frontend/operations/deployment/nginx/production-nginx.conf.example new file mode 100644 index 0000000..5b645a7 --- /dev/null +++ b/aidlc-docs/features/react-frontend/operations/deployment/nginx/production-nginx.conf.example @@ -0,0 +1,55 @@ +# Voorbeeldconfiguratie voor de nginx reverse proxy op de reverse-proxy-Pi +# (dezelfde Pi als reverse-proxy-nginx.conf.example) voor de PRODUCTIEOMGEVING +# van de react-frontend, bereikbaar via slpsoftware.nl / www.slpsoftware.nl. +# +# Dit bestand dekt ALLEEN de react-frontend-site. De daadwerkelijke productie- +# server (pi-entry) regelt op hetzelfde domein ook mail/iRedAdmin-proxying +# (naar een Odroid C4 op 192.168.1.104) — dat zijn aanvullende server-blocks +# die niets met deze feature te maken hebben en bewust buiten dit voorbeeld +# gelaten zijn. Voeg ze desgewenst zelf toe naast dit blok. +# +# Dit is de versie die je gebruikt VOORDAT certbot gedraaid heeft: alleen +# poort 80, geen SSL. Certbot heeft dit HTTP-server-block namelijk nodig om +# de ACME-challenge te kunnen afhandelen en zal, zodra je hem draait, dit +# bestand zelf herschrijven om er de HTTPS-configuratie en de HTTP→HTTPS- +# redirect aan toe te voegen. Zie production-nginx.conf.post-certbot.example +# voor hoe het bestand er na die stap uit gaat zien (puur ter referentie — +# dat bestand hoef je niet zelf te kopiëren, certbot genereert het). +# +# Kopieer dit bestand handmatig naar +# /etc/nginx/sites-available/slpsoftware.conf op de reverse-proxy-Pi, maak +# een symlink in sites-enabled, herlaad nginx, en draai dan pas certbot: +# sudo certbot --nginx -d slpsoftware.nl -d www.slpsoftware.nl +# Zorg dat de DNS-records voor beide domeinen al naar het publieke IP van +# deze Pi wijzen voordat je certbot draait. +server { + listen 80; + listen [::]:80; + + server_name slpsoftware.nl www.slpsoftware.nl; + + error_log /var/log/nginx/slpsoftware_error.log; + access_log /var/log/nginx/slpsoftware_access.log; + + location /.well-known/acme-challenge/ { + root /var/www/certbot; + } + + # Zelfde Sentry-tunnel-endpoint als de testomgeving (zie + # reverse-proxy-nginx.conf.example): VITE_SENTRY_DSN is bewust gedeeld + # tussen test en productie (één Sentry-project, environment-tag + # onderscheidt ze), dus dezelfde org-/project-id hieronder is correct. + location /sentry-tunnel { + proxy_pass https://o4511795618185216.ingest.de.sentry.io/api/4511795622838352/envelope/; + proxy_set_header Host o4511795618185216.ingest.de.sentry.io; + proxy_ssl_server_name on; + } + + location / { + proxy_pass http://192.168.1.103:80; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } +} diff --git a/aidlc-docs/features/react-frontend/operations/deployment/nginx/production-nginx.conf.post-certbot.example b/aidlc-docs/features/react-frontend/operations/deployment/nginx/production-nginx.conf.post-certbot.example new file mode 100644 index 0000000..e0c107d --- /dev/null +++ b/aidlc-docs/features/react-frontend/operations/deployment/nginx/production-nginx.conf.post-certbot.example @@ -0,0 +1,69 @@ +# REFERENTIE ALLEEN — dit bestand hoef je niet handmatig te kopiëren. +# +# Dit toont hoe /etc/nginx/sites-available/slpsoftware.conf op de +# reverse-proxy-Pi er automatisch uit komt te zien NADAT je certbot hebt +# gedraaid (`sudo certbot --nginx -d slpsoftware.nl -d www.slpsoftware.nl`) +# op basis van production-nginx.conf.example. Certbot voegt zelf de HTTPS- +# configuratie en het HTTP→HTTPS-redirect-blok toe (herkenbaar aan de +# "managed by Certbot" commentaren), en zet de error_log/access_log en +# overige location-blocks gewoon over naar het nieuwe HTTPS-serverblok. +# +# Let op de plek van de acme-challenge location: die hoort in dit 443-blok, +# niet in het losse poort-80-blok onderaan. De "if ($host = ...)"-redirects +# daar worden door nginx in de rewrite-fase uitgevoerd, vóór location- +# matching — een acme-challenge location in dat blok zou dus alsnog altijd +# overruled worden door de redirect, en de eerstvolgende certificate- +# renewal zou stilzwijgend falen. +# +# Dit bestand dekt ALLEEN de react-frontend-site (geen mail/iRedAdmin- +# proxying) — zie production-nginx.conf.example voor de toelichting. +server { + + server_name slpsoftware.nl www.slpsoftware.nl; + + error_log /var/log/nginx/slpsoftware_error.log; + access_log /var/log/nginx/slpsoftware_access.log; + + location /.well-known/acme-challenge/ { + root /var/www/certbot; + } + + location /sentry-tunnel { + proxy_pass https://o4511795618185216.ingest.de.sentry.io/api/4511795622838352/envelope/; + proxy_set_header Host o4511795618185216.ingest.de.sentry.io; + proxy_ssl_server_name on; + } + + location / { + proxy_pass http://192.168.1.103:80; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + + listen 443 ssl; # managed by Certbot + listen [::]:443 ssl; # managed by Certbot + ssl_certificate /etc/letsencrypt/live/slpsoftware.nl/fullchain.pem; # managed by Certbot + ssl_certificate_key /etc/letsencrypt/live/slpsoftware.nl/privkey.pem; # managed by Certbot + include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot + ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot + +} + +server { + if ($host = www.slpsoftware.nl) { + return 301 https://$host$request_uri; + } # managed by Certbot + + if ($host = slpsoftware.nl) { + return 301 https://$host$request_uri; + } # managed by Certbot + + + listen 80; + listen [::]:80; + + server_name slpsoftware.nl www.slpsoftware.nl; + return 404; # managed by Certbot +}