SluijsensandClaude Sonnet 5
a208aebae0
Voegt build-production en deploy-production jobs toe aan continuous_integration.yaml, alleen actief bij een handmatige workflow_dispatch-run met het deploy_production-vinkje aangevinkt (nooit automatisch bij een push naar master). Een aparte build-production job is nodig omdat VITE_APP_ENV een build-time Vite-variabele is: dezelfde bundel kan niet zowel als test als production getagd zijn in Sentry/analytics. Uploadpad komt uit de nieuwe Gitea-variable DEPLOY_PATH_PRODUCTION, analoog aan DEPLOY_PATH_TEST. Documentatie en production-readiness-checklist bijgewerkt om dit open item als opgelost te markeren. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
44 lines
6.8 KiB
Markdown
44 lines
6.8 KiB
Markdown
# Deployment Plan
|
|
|
|
## Chosen Method
|
|
**Gitea Actions**, opgesplitst in twee workflow-bestanden:
|
|
- `.gitea/workflows/continuous_integration.yaml` — draait de build/test/lint-gate, automatisch bij elke pull request (ongeacht branch) en bij elke push/merge naar `master`, of handmatig via `workflow_dispatch`. De `deploy-test`-job zelf blijft daarnaast ook beperkt tot `master`/`workflow_dispatch` via een eigen `if`-check.
|
|
- `.gitea/workflows/deploy.yaml` — een herbruikbare (`workflow_call`) job die de `dist/` build via SCP (over SSH) uploadt naar de webroot van een omgeving.
|
|
|
|
Sinds deze stap is er een echte, geautomatiseerde upload naar een **testomgeving**: een Raspberry Pi die de statische site serveert via nginx, achter een tweede Raspberry Pi die als nginx reverse proxy fungeert.
|
|
|
|
## How It Works
|
|
1. Bij elke pull request draait automatisch de build/test/lint-gate (`prepare` → `build` → `test`), zodat merge requests direct gevalideerd worden.
|
|
2. Zodra een pull request naar `master` gemerged wordt (of de workflow handmatig via `workflow_dispatch` gestart wordt), draait aanvullend de `deploy-test` job.
|
|
3. `deploy-test` roept de herbruikbare `deploy.yaml` workflow aan met `artifact_name`/`environment`/`deploy_path`, en geeft via `secrets: inherit` de Pi-inloggegevens door. Deze drie waarden (samen met de artifact-naam/pad die de `build`-job gebruikt) staan als variabelen in het `env:`-blok bovenaan `continuous_integration.yaml` (`ARTIFACT_NAME`, `ARTIFACT_PATH`, `DEPLOY_ENVIRONMENT`, `DEPLOY_PATH`), en worden via een kleine `config`-job als job-outputs doorgegeven aan `deploy-test` (nodig omdat de `env`-context zelf niet werkt in de `with:`-sectie van een reusable-workflow-aanroep). `DEPLOY_PATH` zelf is geen hardcoded waarde meer, maar wordt gelezen uit de Gitea repository variable `DEPLOY_PATH_TEST` (`Repository → Settings → Actions → Variables`), zodat het uploadpad aangepast kan worden zonder de workflow te wijzigen — zie `deployment-instructions.md`.
|
|
4. `deploy.yaml` downloadt de artifact en uploadt de inhoud via een `scp`-commando (met `sshpass` voor het wachtwoord) in een gewone shell-stap naar de webserver-Pi op het interne netwerk (`192.168.1.103`, poort `2224`). Dit vervangt de eerdere `appleboy/scp-action` (Docker-container-action), die faalde op de zelf-gehoste Podman-runner (`failed to attach to container: unable to upgrade to tcp, received 409`).
|
|
5. nginx op de webserver-Pi serveert de bestanden vanaf `/mnt/storage1/www/html/test/slpsoftware`; de reverse-proxy-Pi stuurt binnenkomend verkeer door naar deze webserver-Pi. Voorbeeldconfiguraties staan in `operations/deployment/nginx/` en zijn de daadwerkelijk in gebruik zijnde configuraties (niet langer illustratieve concepten).
|
|
6. De reverse-proxy-Pi is ook verantwoordelijk voor SSL: certificaten worden net als voorheen aangevraagd via certbot (Let's Encrypt) en HTTP-verkeer wordt doorverwezen naar HTTPS.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## Rollback Strategy
|
|
Zie `rollback-plan.md` — voor de testomgeving kan een eerdere commit/branch opnieuw gebouwd en geüpload worden door de workflow opnieuw te triggeren.
|
|
|
|
## Secrets & Configuration
|
|
Voor de testomgeving zijn de volgende Gitea Actions Secrets (repository-niveau) vereist:
|
|
- `PI_MAIN_HOST` — `192.168.1.103` (intern IP van de webserver-Pi)
|
|
- `PI_MAIN_PORT` — `2224`
|
|
- `PI_MAIN_USERNAME` — `webadmin`
|
|
- `PI_MAIN_PASSWORD` — het SSH-wachtwoord van deze gebruiker
|
|
|
|
Deze secrets heten bewust `PI_MAIN_*` in plaats van `PI_TEST_*`: alle webhosts gebruiken op dit moment dezelfde inloggegevens (dezelfde Pi), dus de naam is niet omgeving-specifiek. Mocht dat in de toekomst veranderen, dan worden alsnog omgeving-specifieke secrets geïntroduceerd.
|
|
|
|
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.
|
|
|
|
## 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.
|