Adds Gitea Actions CI/CD for test and production
Continuous Integration / check (pull_request) Failing after 6m55s
Continuous Integration / lighthouse (pull_request) Skipped
Continuous Integration / deploy-test (pull_request) Skipped
Continuous Integration / deploy-production (pull_request) Skipped

The pipeline runs lint, format, tests, build, dependency audit and
Lighthouse (mobile and desktop, Playwright Chromium on the arm64 runner)
on every pull request, push to master and manual run.

Pushes to master deploy to test automatically, and any branch can be
deployed to test manually. Test is a Raspberry Pi with nginx next to the
current WordPress site; the deploy refuses folders containing WordPress.
Production deploys are manual and only from release/* branches, over
FTP with TLS to the IIS webhost.

The IIS web.config and both nginx configs are generated from the same
security header list as the Vite servers, with a test that fails when
the generated files drift. Adds .gitattributes for LF line endings and
pins pnpm through packageManager.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-19 00:18:51 +02:00
co-authored by Claude Opus 5.5
parent 069c7cb7eb
commit e6436601a4
20 changed files with 1394 additions and 10 deletions
@@ -0,0 +1,89 @@
# Deployment Clarification Questions — frontend-shell
Je antwoorden in [deployment-setup-plan.md](deployment-setup-plan.md) brengen een paar keuzes boven die ik niet zelf kan maken. Vul per vraag de letter in na `[Answer]:`.
Wat ik van de hoster weet ([pakketpagina](https://www.mijnhostingpartner.nl/pg/info/aspnet-core-hosting/)): Windows-hosting met **URL Rewrite**, dus IIS. Security headers en de SPA-fallback gaan daar via een `web.config` naast `index.html`. Over FTP/SFTP/SSH staat niets op de pagina.
---
## Vraag 1: Branchstrategie
Je vroeg om advies over gitflow tegenover trunk-based.
**Gitflow**: `develop` voor lopend werk, `release/x.y`-branches voor een release, en daarna terugmergen naar `develop` én `master`, met een tag. Bedacht voor teams die meerdere versies tegelijk onderhouden of op vaste momenten releasen. Voor één ontwikkelaar levert het vooral extra merges op, en kans op merge-conflicten tussen `develop` en `master`.
**Trunk-based (lichte variant)**: `master` is altijd releasebaar. Werk gebeurt in korte feature-branches die via een pull request naar `master` gaan, zoals je nu al doet. Een release is een **tag** op `master` (bv. `v1.2.0`).
Mijn advies voor jouw situatie (één ontwikkelaar, een test- en een productieomgeving) is **trunk-based met release-tags**. Het past bij hoe je nu werkt, en alles wat je met gitflow wilde blijft mogelijk:
| Jouw wens | Trunk-based met tags |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Altijd en snel naar test, ook een specifieke versie | Handmatige "Deploy naar test" in Gitea met keuze van branch, commit of tag. Daarnaast automatisch bij elke merge naar `master`. |
| Productie alleen vanuit een release | Productie alleen vanaf een tag `v*`, handmatig gestart in Gitea |
| Een vaste versie kunnen terugzetten | Elke tag is een vaste versie; terugzetten is die tag opnieuw deployen |
A) Trunk-based met release-tags **(aanbevolen)**
B) Gitflow zoals je beschreef: `develop`, `release/*`, `master` met tags. Productie alleen vanaf `release/*`.
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: x, ik wil een mix welke volgens mij nog steeds dichter bij trunk-based ligt. Ik wil release en feature branches om het werk nog wel geisoleerd te houden. Mocht het helemaal kapot gaan kan je de branch weggooien en zo kan ik nog steeds PR's gebruiken als jij dingen oppakt. Dan kan ik makkelijker de PR checken voor de veranderingen en bij mergen van de PR kan een test-release gedaan worden. Maar ik wil dan de develop branch er tussenuit halen. Ik ben volgens mij vergeten aan te geven dat na het succesvol mergen van een PR een workflow moet worden gestart met een deploy naar test als automatische deploy. Een deploy naar test moet ook handmatig kunnen om op test te kunnen deployen om iets te testen voordat de PR wordt gemerged.
## Vraag 2: Wanneer gaat de nieuwe site live?
De eerste deployment naar productie vervangt wat er nu op `andreaslop.nl` staat. De nieuwe site heeft nog alleen placeholderpagina's ("in de maak").
A) De productie-pipeline nu bouwen en testen, maar de eerste echte productie-deployment pas starten als de pagina's inhoud hebben. Tot die tijd alleen de testomgeving. **(aanbevolen)** Door de handmatige start kan het niet per ongeluk gebeuren.
B) Zodra de pipeline werkt live gaan, ook met placeholders
C) De huidige site staat ergens anders; productie op deze hoster is nog leeg
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A, mogelijk kan het eerder worden gedeployed, maar dat kan ook handmatig gestart worden. De huidige site staat op een andere host dus als ik de DNS daar nog naar toe verwijs zou het geen impact moeten hebben.
## Vraag 3: Hoe komen de bestanden bij de productiehoster?
Kijk in het hostingpaneel welke toegang je hebt.
A) SFTP **(aanbevolen als beschikbaar)** Versleuteld en eenvoudig vanuit de pipeline.
B) Alleen FTP met TLS (FTPS)
C) Alleen gewone FTP (onversleuteld). Werkt, maar dan gaat het wachtwoord onversleuteld over het internet; liever niet.
D) Web Deploy (msdeploy), als de hoster dat aanbiedt
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B, Meer info op: https://www.mijnhostingpartner.nl/client/knowledgebase/ftp/ftp-verbinding-opzetten/
## Vraag 4: Wat draait er op je testserver?
De testomgeving moet zich zoveel mogelijk als productie gedragen (headers, SPA-fallback).
A) Windows met IIS, net als productie. Dan gebruik ik dezelfde `web.config` en dezelfde deploymethode.
B) Linux met een webserver (nginx, Apache of Caddy), bereikbaar via SSH. Dan stel ik een gelijkwaardige config op, en deploy ik via SSH/rsync.
C) Linux, maar alleen via SFTP bereikbaar
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B, maar dan een raspberry pi server met Nginx die weer achter een andere Raspberry pi zit die als reverse proxy is ingesteld.
## Vraag 5: Chrome voor Lighthouse in de pipeline
Je runner draait de jobs waarschijnlijk in **Docker-containers**; dat is de standaard bij `act_runner`. Een Chrome die op de server zelf staat, is dan in de container niet zichtbaar.
A) De pipeline installeert zelf Chromium in de job (één regel, vaste versie uit de Debian-repository). Werkt ongeacht wat er op de server staat. **(aanbevolen)**
B) De runner draait jobs direct op de server (host-modus), en dan gebruik ik de Chrome die daar staat
C) Weet ik niet. Ik zoek de runner-labels op in Gitea (Site Administration of Settings → Actions → Runners) en vul ze hieronder in.
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: Ik denk B, De runner is `raspberry-pi-arm64` met versie v2.1.0, is een Global runner met de labels linux-arm64 en ubuntu-latest. Kijk in `K:\Development\SlpSoftware\Projects\SlpSoftware` en `K:\Development\Projects\SlpModularCms` hoe het dara gedaan is. Dat draait er nu ook, maar bedenk dat die wel volledig op de eigen server draaien dus nmiet alles klakkeloos overnemen.
---
## Ter info: databasemigraties en terugdraaien (je vraag bij Vraag 8)
Dit speelt pas als de API er is, maar het antwoord bepaalt nu al de aanpak:
- **Migraties via de pipeline kunnen.** Met Entity Framework Core maak je bij het bouwen een migratiescript of "migration bundle". De pipeline voert dat uit vóór de nieuwe API live gaat.
- **Databasemigraties terugdraaien is riskant.** Een "down"-migratie kan data weggooien, bijvoorbeeld bij een verwijderde kolom. Gangbaar is daarom:
- **Achterwaarts compatibele migraties** (expand/contract). Een kolom hernoemen gaat in twee releases: eerst de nieuwe kolom erbij, en pas later de oude weg. De vorige versie van de API werkt dan nog met de nieuwe database.
- **Terugdraaien** = de vorige versie van de code deployen, met de database zoals die is (jouw keuze B).
- **Echte fouten in data of schema** los je op met een nieuwe migratie vooruit ("roll forward"), niet door terug te draaien.
- **Kleine database (50 MB)**: maak vóór elke productiemigratie een back-up of export; de pipeline kan dat aanroepen.
Dit neem ik op in het rollback-plan als richtlijn voor de API-feature. Voor de huidige statische site is terugdraaien simpelweg de vorige tag opnieuw deployen.
@@ -0,0 +1,108 @@
# Deployment Setup Plan — frontend-shell
## Context
- **Code**: `web/` (static SPA). `pnpm build` produces `dist/`. `pnpm check` runs lint, format, tests, build, audit and Lighthouse.
- **Git hosting**: self-hosted Gitea at `gitea.slpsoftware.nl`. There is no CI configuration yet (`.gitea/workflows` and `.github` do not exist).
- **Back-end**: `api/` exists but is empty; the .NET API comes later.
- **Carried-forward requirements**:
- `pnpm check` runs on every push (NFR follow-up 1).
- The production host sends the security headers (NFR-SEC-01/02).
- The SPA fallback: every unknown path serves `index.html`, so deep links like `/portfolio` work.
## Plan
- [x] 1. Answer the questions below
- [x] 2. Analyze answers (follow-up questions if needed)
- [x] 3. Generate `operations/deployment/deployment-plan.md`
- [x] 4. Generate the pipeline definition(s) in the repository, plus `operations/deployment/deployment-instructions.md`
- [x] 5. Generate `operations/deployment/rollback-plan.md`
- [x] 6. Fix line endings (see below) and verify the pipeline steps locally
## Already decided (no question needed)
- **Line endings**: a `.gitattributes` with `* text=auto eol=lf` (binary files excepted).
- Today Git converts files to Windows line endings (CRLF) on checkout, while Prettier requires LF. A fresh checkout on Windows can therefore fail `pnpm check`, and the CI runner and your machine would see different files.
- Your editor keeps working as before; files are simply stored and checked out with LF everywhere.
- **Pipeline order**: install with the lockfile, then `pnpm check`. Deployment only happens when that passes.
- **Secrets**: deployment credentials go in Gitea's encrypted Actions secrets, never in the repository.
---
## Questions
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe. Waar ik een voorkeur heb staat **(aanbevolen)**.
### Vraag 1: Deployment opzetten voor deze feature?
A) Ja, help me deployment op te zetten
B) Nee, deployment gebeurt elders of is niet nodig
C) Weet ik niet, stel een aanpak voor en ik beslis
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 2: Welk CI-systeem?
Gitea heeft een ingebouwd CI-systeem, **Gitea Actions**, met dezelfde workflow-syntax als GitHub Actions. Het heeft wel een **runner** nodig: een klein programma (`act_runner`) op een server, dat de jobs uitvoert.
A) Gitea Actions **(aanbevolen)** Zit in je Gitea, geen extra dienst, en de workflows zijn later eenvoudig naar GitHub over te zetten.
B) Een aparte CI-dienst (bv. Woodpecker, Jenkins)
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 3: Is er al een runner voor Gitea Actions?
A) Ja, er draait al een runner die ik voor dit project kan gebruiken
B) Nee. Neem in de instructies op hoe ik er een opzet (met Docker op een eigen server of pc) **(aanbevolen als er nog geen is)**
C) Weet ik niet, ik controleer het
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
### Vraag 4: Waar wordt de website gehost?
A) Op een eigen server (bv. dezelfde als Gitea), met een webserver zoals Caddy of nginx. De pipeline zet de bestanden er via SSH/rsync neer. Volledige controle over security headers en de SPA-fallback. **(aanbevolen als je een eigen server hebt)**
B) Bij een webhoster met FTP/SFTP-toegang, bijvoorbeeld waar de huidige statische site staat. Headers en fallback dan via `.htaccess` (Apache), als de hoster dat toestaat.
C) Een static-hostingdienst (bv. Cloudflare Pages, Netlify, of een Europese variant). Weinig beheer, headers via een configbestand.
D) Nog niet bekend: zet nu alleen de CI op (bouwen en testen bij elke push) en de deployment later
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: X, voor productie wordt dat een webhoster met ftp/sftp toegang. Voor de testomgeving heb ik een eigen server, maar heb ik eventueel ook toegang met ftp/sftp. Ik heb alleen maar 1 website die ik kan hosten dus zodra ik de API ga bouwen die uit een ander project gaat komen moet de website als static files worden geserveerd door de API. Dit is een pagina met meer info over de webhost: https://www.mijnhostingpartner.nl/pg/info/aspnet-core-hosting/ en het gaat dan om het ASP.NET Core 10 Hosting pakket
### Vraag 5: Welke omgevingen?
A) Alleen productie
B) Test/staging (bv. `test.andreaslop.nl`) en productie. Je ziet een wijziging eerst op test voordat hij live gaat. **(aanbevolen)**
C) Ook een preview per pull request
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
### Vraag 6: Wanneer wordt er gedeployd?
A) Automatisch: elke merge naar `master` gaat live (en, bij een testomgeving, elke push naar een feature-branch naar test)
B) Automatisch naar test; naar productie pas na een handmatige goedkeuring of start in Gitea **(aanbevolen)**
C) Altijd handmatig starten
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B, ik wil de gitflow gaan toepassen. Naar test moet altijd kunnen. Zodat er makkelijk en snel een specifieke versie op de test-omgeving gedeployed of geredeployed kan worden. Naar productie mag alleen vanaf een release-branch. DIe branch wordt daarna teruggemerged naar develop en master en op master wordt dan een tag gezet. Ik heb ook van trunk-based gehoord. het zou kunnen dat dat praktischer is. Ik laat mij graag aanbevelen wat handiger is voor mij.
### Vraag 7: Lighthouse in de pipeline
`pnpm check` draait ook Lighthouse, en daarvoor moet er Chrome in de runner zitten. Dat maakt de pipeline een paar minuten langer.
A) Ja, de volledige `pnpm check`, inclusief Lighthouse, in de pipeline. De runner gebruikt een image met Chrome. **(aanbevolen)** Dit was jouw wens: een vergeten lokale check wordt dan alsnog opgevangen.
B) In de pipeline alles behalve Lighthouse; Lighthouse alleen lokaal
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: ik heb een headless browser op de gitea/buildserver staan. Als het goed is is dat chrome, maar niet meer helemaal zeker.
### Vraag 8: Terugdraaien bij een mislukte release
A) De server bewaart de laatste paar releases. Terugdraaien is één commando of één klik in Gitea, die terugwisselt naar de vorige release. **(aanbevolen bij een eigen server)**
B) Terugdraaien door de vorige commit opnieuw door de pipeline te laten deployen
X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B als dat kan en ook gezien de database. Ik weet niet of er via de pipeline een migratie kan worden gedaan en ook terug worden gedraaid zodra we een API hebben?