Files
slp-modular-cms/README.md
T
SluijsensandClaude Sonnet 5.5 321234dfa6 CMS: één bannerlijst met Locatie, SLP-thema, thema-schakelaar, documentatie
- Banner-admin: één lijst met Locatie-badge (Boven/Onder), Locatie-keuzeveld in het formulier, "Live" en "Wordt niet getoond" per locatie, aan/uit per rij
- Thema slpsoftware: Archivo, bordeaux #7A1414 (WCAG AA licht en donker), <SLP/>-logo, favicon, mail-logo; VITE_THEME in de SLP-builds (test en productie-config)
- Thema-schakelaar: eerste klik wisselt altijd het getoonde thema (klasse op <html> als bron van waarheid, gedeelde status, startscript valideert opslag) + tests
- Docs: README, docs/cms-themas.md, docs/deploy-en-testomgevingen.md, docs/privacy-gegevens-contactformulier.md, aidlc-docs (offering-banners, bug theme-toggle-first-click)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-15 00:14:10 +01:00

389 lines
31 KiB
Markdown

# SlpModularCms
Een modulaire monolith CMS gebouwd met .NET 10.
## Projectstructuur
- `src/SlpModularCms.Api`: De host applicatie en API shell (lokale ontwikkeling / dev-host).
- `src/SlpModularCms.Api.SlpSoftware`: Tweede Client-project, de daadwerkelijk gedeployde API voor `test.slpsoftware.nl`/`slpsoftware.nl` (CI/CD-cutover vanaf `SlpModularCms.Api`). Host dezelfde modules als `SlpModularCms.Api` via dezelfde gedeelde `CmsHost`-compositie (zie hieronder), plus de `Offerings`- en `Contact`-module. Heeft een eigen, geïsoleerde lokale ontwikkeldatabase — zie `appsettings.Development.json` in dat project.
- `src/SlpModularCms.Api.AndreaSlopFotografie`: Derde Client-project voor Andrea Slop Fotografie (testomgeving `test.andreaslop.nl`). Host de modules `Identity`, `Availability`, `Offerings` en `Contact` (geen `Master`) en serveert de voorgerenderde website uit `wwwroot/web/` (`WebsiteMode.PrerenderedPages`) plus de admin met het thema `asf` op `/admin`. Lokaal op poort `5200`, eigen database (`appsettings.Development.json`). Bijbehorende tests: `SlpModularCms.Api.AndreaSlopFotografie.Tests` (de pipelinetests daarin hebben net als `Api.Tests` een bereikbare MariaDB nodig).
- `src/SlpModularCms.Core`: Kern functionaliteiten, data modellen en interfaces. Bevat ook `Core/Hosting/CmsHost.cs` — de gedeelde service- en pipeline-compositie die elk Client-project (`Api`, `Api.SlpSoftware`) vanuit zijn eigen dunne `Program.cs` aanroept, zodat beide projecten niet uit elkaar kunnen groeien.
- `src/SlpModularCms.Modules.*`: Onafhankelijke functionele modules.
- `frontend/`: De CMS admin web-UI (Vite + React + TypeScript). Bewust buiten `src/` gehouden om de .NET solution schoon te houden.
## Development Setup
### Vereisten
- .NET 10 SDK
- Podman of Docker (voor MariaDB)
### 1. Database opstarten
Start een MariaDB-container met de volgende opdracht:
```powershell
podman run -e "MARIADB_ROOT_PASSWORD=<your_password>" -p 3306:3306 --name mariadb -d docker.io/library/mariadb:latest
```
> **Migratie-notitie**: dit project draaide tot 2026-07-28 op Microsoft SQL Server. Overgestapt naar
> MariaDB omdat de productie-Pi geen SQL Server kan draaien (geen ARM64-build bestaat) en al MariaDB
> heeft geïnstalleerd. Zie `aidlc-docs/features/gitea-deployment-workflow/` voor de volledige
> rationale. Bestaande lokale SQL Server-databases/migraties zijn niet compatibel — begin met een
> verse MariaDB-database.
### 2. Configuratie
De applicatie maakt gebruik van een drie-bestanden patroon voor configuratie:
- `appsettings.json`: Productie baseline.
- `appsettings.Development.json`: Ontwikkelinstellingen.
- `appsettings.local.json`: Lokale overrides (niet in Git).
Zorg dat er een `src/SlpModularCms.Api/appsettings.local.json` aanwezig is met de juiste connection string:
```json
{
"ConnectionStrings": {
"DefaultConnection": "Server=127.0.0.1;Port=3306;Database=SlpModularCms;Uid=root;Pwd=<your_password>"
}
}
```
### 3. Applicatie starten
Voer de applicatie uit vanaf de root:
```powershell
dotnet run --project src/SlpModularCms.Api
```
De API is daarna bereikbaar op `https://localhost:7221` (of de geconfigureerde poort). De OpenAPI documentatie (Scalar) is beschikbaar op `/scalar`.
`SlpModularCms.Api.SlpSoftware` start op dezelfde manier (`dotnet run --project src/SlpModularCms.Api.SlpSoftware`, bereikbaar op `https://localhost:7223` — `7222` is al in gebruik door `SlpModularCms.Api.Slave`), maar verwacht een **eigen**, aparte lokale database (zie dat project's eigen `appsettings.Development.json`) — niet dezelfde als `SlpModularCms.Api`.
## Initiële Setup (Bootstrapping)
...
## Authenticatie & Security (Unit 0)
De API gebruikt een beveiligde flow voor authenticatie:
- **Login**: `POST /api/v1/auth/login`. Retourneert een `accessToken` in de body en een `refreshToken` in een beveiligde `httpOnly` cookie.
- **Refresh**: `POST /api/v1/auth/refresh`. Gebruikt de `refreshToken` cookie om een nieuwe `accessToken` en `refreshToken` (rotatie) te genereren.
- **Revoke**: `POST /api/v1/auth/revoke`. Trekt het token in en wist de cookie.
### Belangrijke NFR Details:
- **CORS**: Alleen toegestane origins uit `appsettings.json → Cors:AllowedOrigins` worden geaccepteerd. De frontend moet draaien op een van deze origins.
- **Cookies**: De `refreshToken` cookie is `httpOnly`, `SameSite=Strict` en heeft het pad `/api/v1/auth`.
- **Rate Limiting**: Login endpoints hebben rate limiting (Fixed window 5/min, Sliding window 20/min). De limieten gelden **per clientadres**. Achter een reverse proxy is dat alleen het echte bezoekersadres als `ForwardedHeaders__KnownProxies__0` (en volgende) het IP van de proxy bevat; zonder die instelling worden `X-Forwarded-*`-headers genegeerd en delen alle bezoekers het adres van de proxy (één bucket, het gedrag van vóór deze optie). Alleen de opgegeven proxies worden vertrouwd (één hop); een onparseerbaar of wildcard-adres (`0.0.0.0`, `::`) laat de host bij **opstarten** falen.
- **Error Handling**: Foutmeldingen volgen de RFC 9457 `ProblemDetails` standaard.
## E-mail (uitnodigingen, wachtwoord opnieuw instellen, meldingen)
E-mail staat standaard UIT: zolang `Email:Smtp:Host` leeg is, werkt alles zoals voorheen (de beheerder kopieert de uitnodigingslink). Aanzetten per omgeving met omgevingsvariabelen (geheimen nooit in een bestand in de repo):
| Variabele | Voorbeeld |
|---|---|
| `Email__Smtp__Host` | `mail.slpsoftware.nl` (zet e-mail aan) |
| `Email__Smtp__Port` / `Email__Smtp__EnableSsl` | `587` / `true` (STARTTLS) |
| `Email__Smtp__Username` / `Email__Smtp__Password` | geheimen, alleen in `shared/env` (mode 600) |
| `App__PublicBaseUrl` | `https://test.andreaslop.nl` (https, zonder pad; http alleen voor localhost) |
| `Email__FromAddress` / `Email__FromName` | `no-reply@slpsoftware.nl` / sitenaam |
| `Email__AllowedFromAddresses__0` | extra afzenderadressen die de eigenaar bij Instellingen mag kiezen |
Lokaal: smtp4dev op `localhost:25` (`Email__Smtp__Host=localhost`, `Email__Smtp__Port=25`, `Email__Smtp__EnableSsl=false`). De opstart weigert een onjuiste mailconfiguratie met een duidelijke melding (zonder geheimen). Afzenderadres en -naam stelt de eigenaar in bij Instellingen, Mail; het adres kan alleen uit de toegestane lijst worden gekozen (SPF/DKIM). Details: `aidlc-docs/features/identity-email-notifications/`.
## Frontend Development (CMS Admin UI)
De frontend is een Vite + React 19 + TypeScript single-page application in de map `frontend/`. Hij gebruikt TanStack Router, Tailwind v4 (hoofdkleur `#ac0000`) met shadcn/ui-stijl componenten, react-i18next (NL/EN), en MSW voor mocking in tests.
### Vereisten
- Node.js 20+ (getest met v24)
- pnpm 9+ (getest met v11)
### Snel starten
```powershell
cd frontend
pnpm install
pnpm dev
```
De dev-server draait op `http://localhost:5173`.
### Configuratie
De frontend leest de API-basis-URL uit een environment-variabele (zie `frontend/.env.example`):
```
VITE_API_BASE_URL=http://localhost:5000
```
Per site kan de admin bij het bouwen een thema en standaardtaal krijgen (beschikbare thema's: `asf` en `slpsoftware`, zie [docs/cms-themas.md](docs/cms-themas.md)): `VITE_THEME=asf` kiest `frontend/themes/asf/theme.css` (alleen CSS-variabelen, zelf gehoste lettertypen via `@fontsource`, plus een eigen favicon; een onbekende themanaam laat de build falen, leeg of afwezig = het standaardthema) en `VITE_DEFAULT_LANGUAGE=nl` (of `en`) bepaalt de taal zolang de gebruiker nog niets koos; een opgeslagen keuze wint altijd.
Kopieer `.env.example` naar `.env.local` en pas de waarde aan indien nodig. Optioneel kan met `VITE_ENABLE_MSW=true` de MSW-mockbackend in de browser worden ingeschakeld voor frontend-ontwikkeling zonder draaiende API.
### Vereiste backend
De app verwacht de .NET API (Unit 0) draaiend op de geconfigureerde origin met:
- **CORS** die de frontend-origin (`http://localhost:5173`) toestaat met `credentials`.
- De `httpOnly` `refreshToken` cookie op pad `/api/v1/auth` (silent refresh bij opstarten).
- RFC 9457 `ProblemDetails` foutmeldingen.
> Let op: de API-poort in `.env.example` (`5000`) moet overeenkomen met de werkelijke API-poort en de `Cors:AllowedOrigins` configuratie van de backend.
### Scripts
```powershell
pnpm dev # ontwikkelserver (HMR)
pnpm build # type-check (tsc) + productie-build
pnpm preview # productie-build lokaal bekijken
pnpm test # unit/integratietests (Vitest + Testing Library + MSW)
pnpm test:coverage # tests met coverage-rapport
pnpm lint # ESLint
pnpm format # Prettier (4-space indent)
```
## Database Migraties
Alle database commando's moeten worden uitgevoerd vanaf de **root** van de projectmap.
### Nieuwe migratie toevoegen
Wanneer je wijzigingen aanbrengt in de modellen (in `SlpModularCms.Core`):
```powershell
dotnet ef migrations add <NaamVanDeMigratie> --project src\SlpModularCms.Core --startup-project src\SlpModularCms.Api
```
### Database bijwerken
Om de migraties toe te passen op de database:
```powershell
dotnet ef database update --project src\SlpModularCms.Core --startup-project src\SlpModularCms.Api
```
### Per-module migraties
Sommige modules (`SlpModularCms.Modules.Master`, `SlpModularCms.Modules.Availability`) hebben een **eigen** `DbContext` met eigen migraties, los van `SlpModularCms.Core`. Deze worden automatisch toegepast bij het opstarten van de applicatie (via `Database.Migrate()` in de module's `UseModule`-methode), maar een nieuwe migratie genereren doe je expliciet per project:
```powershell
dotnet ef migrations add <NaamVanDeMigratie> --project src\SlpModularCms.Modules.Master --startup-project src\SlpModularCms.Api
dotnet ef migrations add <NaamVanDeMigratie> --project src\SlpModularCms.Modules.Availability --startup-project src\SlpModularCms.Api --context AvailabilityDbContext
```
> Let op: voor `SlpModularCms.Modules.Availability` is `--context AvailabilityDbContext` verplicht, omdat de API-startup-project meerdere `DbContext`-typen samenvoegt en de EF CLI anders niet kan bepalen welke bedoeld wordt.
## Nieuwe Module Toevoegen
Het systeem is ontworpen om eenvoudig uitgebreid te worden met nieuwe functionele modules. Volg deze stappen om een nieuwe module toe te voegen:
### 1. Project aanmaken
Maak een nieuw .NET 10 Class Library project aan in de `src/` map. Gebruik de naamconventie `SlpModularCms.Modules.<Naam>`.
```powershell
dotnet new classlib -n SlpModularCms.Modules.MijnNieuweModule -o src\SlpModularCms.Modules.MijnNieuweModule -f net10.0
```
### 2. Referenties toevoegen
Voeg de benodigde referentie naar `Core` toe en voeg het project toe aan de solution:
```powershell
dotnet add src\SlpModularCms.Modules.MijnNieuweModule reference src\SlpModularCms.Core
dotnet sln SlpModularCms.sln add src\SlpModularCms.Modules.MijnNieuweModule
```
### 3. IModule implementeren
Maak een class aan die de `IModule` interface implementeert:
```csharp
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using SlpModularCms.Core.Modules;
namespace SlpModularCms.Modules.MijnNieuweModule;
public class MijnNieuweModule : IModule
{
public string Name => "MijnNieuweModule";
public string Version => "1.0.0";
public void RegisterServices(IServiceCollection services)
{
// Registreer hier module-specifieke services
}
public void UseModule(IApplicationBuilder app)
{
// Configureer hier middleware of andere pipeline zaken
}
}
```
### 4. Registreren in de API
Om ervoor te zorgen dat de module tijdens ontwikkeling wordt meegenomen in de build-output van de API (zodat de `ModuleOrchestrator` de DLL kan vinden), voeg je een referentie toe aan het API project:
```powershell
dotnet add src\SlpModularCms.Api reference src\SlpModularCms.Modules.MijnNieuweModule
```
De `ModuleOrchestrator` zal de module nu automatisch ontdekken en laden bij het opstarten.
## Master CMS Module
De `SlpModularCms.Modules.Master` module laat een Owner op één "Master"-CMS de beschikbaarheid van andere ("slave") CMS-instanties centraal beheren. Elke slave die de `SlpModularCms.Modules.Availability`-module draait, respecteert een master-gecontroleerde aan/uit-status naast zijn eigen lokale beschikbaarheidsschakelaar.
### Architectuur
- **Master** (`SlpModularCms.Modules.Master`): eigen `MasterDbContext` met de `CmsInstance`-entiteit (URL, versleutelde API key, status). Bevat `CmsInstanceController` (`/CmsInstances`, Owner-only), `SlaveApiClient` (uitgaande HTTP-calls naar slaves), `SlaveStatusController` (`GET /api/v1/SlaveStatus`, laat een slave zijn eigen status ophalen) en `IntegrityCheckBackgroundService` (periodieke reconciliatie + status-herpush, standaard elk uur).
- **Slave-extensie** (`SlpModularCms.Modules.Availability`): eigen `MasterRegistration`-entiteit (incl. `LastPolledAt`), `MasterController` (interne endpoints onder `/api/v1/master/*`, buiten de beschikbaarheids-gate om), `MasterStatusPollingBackgroundService` (periodiek pullen van de eigen status bij de Master) en een uitgebreide `AvailabilityMiddleware` die zowel de lokale als de master-gate evalueert.
### Registratie- en statusflow
1. Owner voegt op de Master `/cms`-pagina een slave toe met diens URL.
2. De Master genereert een API key, versleutelt deze (Data Protection) en slaat hem op bij de `CmsInstance`.
3. De Master pusht de registratie naar de slave: `POST /api/v1/master/register` met header `X-Master-Api-Key`.
4. Zet de Owner de status van een slave om (Available / NotAvailable / Inactive), dan pusht de Master dit synchroon door naar de slave. Bij **Inactive** stuurt de Master expliciet `Available` (de gate wordt vrijgegeven — de Master beheert de slave niet meer).
**Twee onafhankelijke synchronisatiepaden** (push én pull), zodat lokale manipulatie of een gemiste update op de slave zichzelf herstelt:
- **Push** (Master → Slave, direct): elke statuswijziging via de UI, plus elke `IntegrityCheckBackgroundService`-cyclus (herpusht de laatst opgeslagen status naar elke actieve slave — vangt slaves op die net herstart zijn).
- **Pull** (Slave → Master, periodiek): `MasterStatusPollingBackgroundService` op de slave haalt zelf zijn status op bij `GET /api/v1/SlaveStatus` (`MasterPolling:PollIntervalSeconds`, standaard 30s). Dit is de guard tegen lokale manipulatie van de slave-status en tegen gemiste pushes.
- **Fail-open**: is de Master langer dan `MasterPolling:FailOpenAfterMinutes` (standaard 5 min) onbereikbaar via de pull, dan valt de slave automatisch terug naar `Available` — een dode of onbereikbare Master mag een slave nooit permanent blokkeren.
### Configuratie
Nieuwe sectie `MasterModule` in `appsettings.json` (zie ook `appsettings.Development.json`):
```json
"MasterModule": {
"IntegrityCheckIntervalMinutes": 60,
"HttpTimeoutSeconds": 10,
"MasterUrl": "https://jouw-master-domein"
}
```
- `MasterUrl` is de publieke URL van déze master-instantie, gebruikt door `IntegrityCheckBackgroundService` (buiten een HTTP-requestcontext heeft de background service geen `HttpContext` om dit uit af te leiden).
Nieuwe sectie `MasterPolling` (op elke instantie die `Modules.Availability` laadt — dus ook de slave):
```json
"MasterPolling": {
"PollIntervalSeconds": 30,
"FailOpenAfterMinutes": 5,
"HttpTimeoutSeconds": 5
}
```
- Heeft geen effect zolang er geen `MasterRegistration` bestaat (bijv. op de Master zelf, of op een slave die nog niet gekoppeld is).
### Vergrendeld Instellingen-scherm op een master-gecontroleerde slave
Zolang de master-gate een slave op `NotAvailable` heeft gezet (via push of pull), toont de slave's eigen `/settings`-pagina (`SettingsPage.tsx`) dit als een vergrendelde toestand in plaats van een normaal te wijzigen instelling:
- Een banner legt uit dat de Master CMS deze status beheert.
- De modusknoppen, het redenveld en de opslaanknop zijn disabled.
- Een lokale poging om de status alsnog te wijzigen (bijv. via een directe API-call) wordt door de backend geweigerd met `409 Conflict` (`MasterControlledAvailabilityException` in `PersistentAvailabilityService.UpdateStatusAsync`) — de master-gate kan dus niet per ongeluk of expres lokaal worden omzeild.
- `GET /api/v1/Availability/status` geeft dit door via het veld `isMasterControlled`.
## Offerings: aanbiedingen en banner
De module `SlpModularCms.Modules.Offerings` (gehost door `Api.SlpSoftware` en `Api.AndreaSlopFotografie`) beheert de aanbiedingen (pakketten, met categorieën) en de banner van de website. Hieronder alleen de banner; details en beslissingen staan in `aidlc-docs/features/offering-banners/overview.md`.
Een banner heeft een **positie**: `top` (smalle balk boven de pagina, één regel) of `bottom` (grote banner; bestaande banners zijn via migratie `20261114100000_AddOfferingBannerPosition` `bottom` geworden).
**Publiek:** `GET /api/v1/offerings/banner?position=top|bottom`
- Zonder `position` geldt `bottom`; een andere waarde geeft `400`.
- `204` zonder actieve banner; anders `200` met `title`, `text`, `linkLabel`, `linkUrl`, `position` (geen planning).
- Anoniem, rate limit `offerings-public` (standaard 120 per 60 s per clientadres, `RateLimiting:OfferingsPublic`), antwoord met `Cache-Control: public, max-age=60`.
**Beheer:** `/api/v1/offerings/banners` (`GET`, `POST`, `PUT {id}`, `DELETE {id}`), alleen voor beheerders (`AdminOnly`).
**Velden en validatie:** `top`: tekst max 120 tekens, titel optioneel. `bottom`: titel verplicht (max 100), tekst max 300. Knoptekst (max 50) en link (max 500) alleen samen; een link is `https://…` of een pad dat met één `/` begint. `endsAt` moet na `startsAt` liggen. `isActive` en de planning (`startsAt`/`endsAt`) bepalen of een banner meetelt.
**"Maximaal één per positie"** geldt bij het uitlezen: je kunt meer banners opslaan en aanzetten; per positie wint de laatst gewijzigde actieve banner die binnen zijn van/tot valt. Een boven- en een onderbanner kunnen dus tegelijk getoond worden.
**Admin** (tabblad Banner bij Aanbiedingen): één lijst met een badge Locatie (Boven/Onder), de status (Actief, Gepland, Verlopen, Uit), de markeringen "Live" (wordt getoond) en "Wordt niet getoond" (actief, maar een nieuwere banner op dezelfde locatie wint), en een aan/uit-knop per rij. Het formulier heeft een keuzeveld Locatie dat de tekstlimiet en de titelplicht aanpast.
## Contactformulier-module
De module `SlpModularCms.Modules.Contact` (gehost door `Api.SlpSoftware` en `Api.AndreaSlopFotografie`; tests in `SlpModularCms.Modules.Contact.Tests`) ontvangt berichten van het contactformulier van een website, slaat ze op, mailt een melding naar de eigenaar en laat beheerders ze in de admin (Berichten) beheren. Plan en beslissingen: `aidlc-docs/features/contact-forms-module/`. Welke gegevens worden bewaard, hoe lang en wat in logs en Sentry terechtkomt: [`docs/privacy-gegevens-contactformulier.md`](docs/privacy-gegevens-contactformulier.md).
- **Uit tenzij beide schakelaars aan staan:** de hostschakelaar `Contact:Enabled` (standaard `false` in beide `appsettings.json`) én de CMS-schakelaar bij Berichten. Is het formulier niet open, dan bestaan de publieke routes niet (404). De migraties van de module worden pas bij het opstarten toegepast als `Contact:Enabled` aan staat.
- **Publiek:** `GET /api/v1/contact-messages/token` (tijdtoken, plus eventuele captcha-gegevens) en `POST /api/v1/contact-messages` (JSON, header `Idempotency-Key` met een GUID; antwoord `202`; fouten `400` in `ProblemDetails`-vorm met veldcodes `required`, `tooLong`, `invalid`, `expired`).
- **Beheer** (`AdminOnly`): `GET /api/v1/contact-messages`, `GET`/`PATCH`/`DELETE …/{id}`, `POST …/{id}/resend`, en `GET`/`PUT /api/v1/contact-settings` (schakelaar) met `PUT …/contact-settings/recipient` (ontvangstadres).
- **Anti-spam:** honeypot, minimumtijd tussen token en verzenden, optioneel Friendly Captcha, rate limiting per clientadres (`RateLimiting:ContactForm`, `ContactToken`, `ContactResend`). Achter een reverse proxy moet `ForwardedHeaders__KnownProxies__0` gezet zijn, anders delen alle bezoekers één limiet.
- **Configuratie (sectie `Contact`):** `Enabled`, `SiteId`, `MinSeconds` (3), `TokenLifetimeMinutes` (120), `RetentionMonths` (12), `SpamRetentionDays` (30), `MaxSpamRowsPerDay` (200), `MaxBodyBytes` (16384), `ProblemTypeBase`, `RecipientEmail` (alleen via omgevingsvariabele `Contact__RecipientEmail`), `Mail:SweepSeconds`/`MaxAttempts`/`BackoffMinutes`/`ClaimMinutes`/`BatchSize`, en `Captcha:Enabled`/`Provider` (`friendlycaptcha`)/`SiteKey`/`Secret` (alleen via `Contact__Captcha__Secret`)/`Region` (`global` of `eu`)/`VerifyUrl`/`TimeoutSeconds`. Een aangezet captcha met ontbrekende of ongeldige instellingen laat de host bij opstarten falen.
- **Opschonen:** een dagelijkse achtergrondtaak verwijdert berichten na hun bewaartermijn en idempotentie-gegevens na 24 uur.
- **Mail:** vereist werkende e-mailconfiguratie (zie "E-mail" hierboven) en een ontvangstadres; anders blijft het bericht bewaard met de reden bij het bericht.
## Lokaal Master + Slave Draaien (Dev)
Om de master↔slave-connectie (zie "Master CMS Module" hierboven) lokaal te kunnen testen, kun je twee backend-instanties tegelijk draaien: een volledige "master" (met de `SlpModularCms.Modules.Master`-module) en een "slave"-instantie zonder die module. Dit is puur een lokale ontwikkel-/testopstelling — er is geen nieuwe functionaliteit aan de master/slave-protocol zelf toegevoegd.
### 1. Backends starten
**Master** (bestaande `SlpModularCms.Api`, ongewijzigd):
```powershell
dotnet run --project src/SlpModularCms.Api --launch-profile https
```
Bereikbaar op `https://localhost:7221` (Scalar op `/scalar`).
**Slave** (nieuwe `SlpModularCms.Api.Slave`, zonder de Master-module):
```powershell
dotnet run --project src/SlpModularCms.Api.Slave --launch-profile https
```
Bereikbaar op `https://localhost:7222` (Scalar op `/scalar`). Vereist een eigen `src/SlpModularCms.Api.Slave/appsettings.local.json` — kopieer `appsettings.local.json.example` naar `appsettings.local.json` en vul een **eigen** lokale database in (bijv. `Database=SlpModularCmsSlave`), zodat master- en slave-data gescheiden blijven.
De `Modules.Availability`-migraties worden automatisch toegepast bij het opstarten (zie "Per-module migraties" hierboven). De `SlpModularCms.Core`-migraties (Identity) worden **nooit** automatisch toegepast — dit moet je, net als bij de master, één keer handmatig doen voor de nieuwe slave-database:
```powershell
dotnet ef database update --project src\SlpModularCms.Core --startup-project src\SlpModularCms.Api.Slave --context ApplicationDbContext
```
### 2. Frontend starten
**Tegen de master** (standaard):
```powershell
cd frontend
pnpm dev
```
Draait op `http://localhost:5173`, gebruikt `.env.local` (`VITE_API_BASE_URL=https://localhost:7221`).
**Tegen de slave** (optioneel, alleen nodig als je de slave ook via de admin-UI wilt bekijken):
```powershell
cd frontend
pnpm dev:slave
```
Draait op `http://localhost:5174`, gebruikt `.env.slave.local` (`VITE_API_BASE_URL=https://localhost:7222`) — kopieer eerst `.env.example` naar `.env.slave.local` met die waarde.
**Beide tegelijk** (zoals een Compound-configuratie in Rider):
```powershell
cd frontend
pnpm dev:all
```
Start `pnpm dev` en `pnpm dev:slave` parallel in één terminal, met gekleurde `master`/`slave`-prefixes per regel zodat de output van elkaar te onderscheiden blijft. Stoppen met `Ctrl+C` sluit beide dev-servers af.
### 3. Slave koppelen aan de master
Met beide backends (en de master-frontend) draaiend:
1. Log in op de master-frontend (`http://localhost:5173`) en ga naar de `/cms`-pagina.
2. Gebruik de bestaande **"Add CMS Instance"**-dialoog om de lokale slave toe te voegen met URL `https://localhost:7222`.
3. De master genereert en pusht een API key naar de slave (`POST /api/v1/master/register`); de instantie zou daarna als **verbonden/gezond** moeten worden getoond.
Zie `aidlc-docs/features/local-dev-master-slave-setup/inception/requirements/requirements.md` voor de volledige requirements en rationale achter deze opstelling.
## Productie Setup
### 0. Routing op de webhost
Op een shared-hosting omgeving (zoals mijnhostingpartner.nl) is er meestal maar ruimte voor 1 website/app-pool. Daarom serveert `SlpModularCms.Api` alles zelf, vanuit één proces:
| Pad | Inhoud |
|---|---|
| `/` | De publieke website van de klant, uit `wwwroot/web/` — **geen onderdeel van deze repo**. Zie [`WEBSITE_WORKSPACE.md`](WEBSITE_WORKSPACE.md) voor het volledige contract (verplichte structuur, verboden/gereserveerde paden, SPA-fallback, same-origin API-calls, CSP, Umami) |
| `/admin` | De CMS admin-UI (`frontend/`), gebouwd met `base: '/admin/'` en automatisch gekopieerd naar `wwwroot/admin/` bij `dotnet publish` |
| `/api/v1/...` | Deze API |
| `/health` | Infrastructuur-liveness — zie "Health-check endpoint" hieronder |
Beide SPA's krijgen een fallback naar hun eigen `index.html` zodat client-side routes (bijv. `/admin/dashboard`) werken; ontbrekende bestanden (met een extensie, bijv. `/admin/assets/x.js`) blijven gewoon 404'en. Zie `Program.cs` (`MapFallbackToFile`) en `SlpModularCms.Api.csproj` (`BuildAndCopyAdminFrontend`-target).
Ontbreekt `wwwroot/web/` nog (een verse deployment vóórdat een website-workspace er iets in heeft gezet), dan start de applicatie gewoon door en toont `/` een ingebouwde placeholder-pagina — `/admin` en `/api/v1` blijven onverminderd werken.
Voor lokale ontwikkeling verandert er niets: `pnpm dev` blijft op `http://localhost:5173` draaien zonder `/admin`-prefix.
### 1. Build & Publish
Publiceren gebeurt via de Gitea Actions-pipeline (`.gitea/workflows/continuous_integration.yaml` → `deploy-scp.yaml`), niet met een losse handmatige `dotnet publish`-stap: elke push naar `master` deployt automatisch naar de SlpSoftware-testomgeving (en naar de ASF-testomgeving als de Gitea-variabele `ASF_TEST_DEPLOY_ENABLED` op `true` staat), productie alleen via een expliciete `workflow_dispatch` met de `deploy_production`-vlag aan. Een branch naar test deployen kan met een handmatige run (`deploy_test` en/of `deploy_asf_test`). Zie [`docs/deploy-en-testomgevingen.md`](docs/deploy-en-testomgevingen.md) voor invoer, testhosts, vereiste variabelen en secrets (alleen namen) en rollback. De pipeline publiceert framework-dependent voor `linux-arm64` en bouwt daarbij automatisch ook de admin-frontend mee naar `wwwroot/admin/`.
Elke deploy plaatst de nieuwe release in een verse map en wisselt pas daarna atomisch over naar `current` — er is dus nooit een moment waarop de applicatie een halfklare release serveert, en `wwwroot/web/` (de klantsite) staat structureel buiten die verwisselde map, zodat een deploy hem nooit kan raken. Volledige host-setup, rollback-procedure en de exacte deploy-stappen staan in de Operations-documentatie van deze feature, niet hier — dit README beschrijft alleen wat er gebouwd is, niet hoe je het voor het eerst inricht.
Wil je toch lokaal handmatig publiceren (bijv. om de output te inspecteren):
```powershell
dotnet publish src/SlpModularCms.Api -c Release -r linux-arm64 --self-contained false -o ./publish
```
### 2. Runtime Configuratie
In productie moeten gevoelige instellingen worden doorgegeven via Environment Variables:
- `ConnectionStrings__DefaultConnection`
- `JwtSettings__Secret`
- `JwtSettings__Issuer`
- `JwtSettings__Audience`
- `MasterModule__MasterUrl` — publieke URL van deze master-instantie (alleen relevant als de Master CMS Module actief is)
- `ForwardedHeaders__KnownProxies__0`, ... — IP-adres(sen) van de reverse proxy voor deze host (optioneel; zie Rate Limiting hierboven). De proxy moet `X-Forwarded-For` en `X-Forwarded-Proto` doorgeven
- `Identity__Setup__Token` — optioneel beschermingstoken voor het aanmaken van de eerste beheerder (`POST /api/v1/Setup/owner` verwacht dan de header `X-Setup-Token`; `GET /api/v1/Setup/status` meldt `tokenRequired`). Minstens 32 willekeurige tekens; alleen-witruimte laat de host falen bij opstarten. Beide setup-endpoints vallen onder de `login`-limiter en een geweigerd token wordt gelogd als beveiligingsgebeurtenis `setup_token_rejected` (event-id 5007, nooit met het token zelf). Verwijder de variabele zodra de eerste beheerder bestaat
- `Observability__SentryDsn` — leeg is een normale, ondersteunde staat: Sentry wordt dan overgeslagen en alleen console-logging blijft actief
- `SecurityHeaders__AllowedScriptOrigins__0`, `SecurityHeaders__AllowedConnectOrigins__0`, ... — externe origins die de CSP van `/admin` en `/api/v1` mag toestaan (bijv. de Umami-scripthost en Sentry's ingest-endpoint). Zie `appsettings.json → SecurityHeaders` voor de volledige optiesvorm; een onbekende `PathPolicies`-policy-naam laat de applicatie bij **opstarten** falen, niet pas bij de eerste request
- **Voorgerenderde website (`WebsiteMode.PrerenderedPages`)** — een client kiest dit in zijn `Program.cs` via `CmsHostOptions` (standaard `SpaFallback`: alles blijft zoals het was). Instellingen voor deze modus: `Website__NoIndex=true` (testinstantie: `X-Robots-Tag` plus `robots.txt` met `Disallow: /`), `SecurityHeaders__DefaultPolicy=StrictSite` met `SecurityHeaders__AllowedSiteScriptOrigins__0`, `SecurityHeaders__AllowedSiteConnectOrigins__0`, ... (alleen gebruikt door `StrictSite`). Logging van de website (301's en 404's op `Information`) gaat via de logger-categorie `SlpModularCms.Website`: zet per omgeving `Website__LogLevel` (test `Information`, standaard en productie `Warning`; leeg = `Logging:LogLevel` beslist). Gebruik niet `Logging__LogLevel__SlpModularCms.Website` in een systemd-`EnvironmentFile`: een variabelenaam met een punt wordt daar genegeerd. Gedrag per pad staat in [`WEBSITE_WORKSPACE.md`](WEBSITE_WORKSPACE.md).
### 2a. Data Protection key ring (Master CMS Module)
De API keys van geregistreerde slaves worden versleuteld opgeslagen met ASP.NET Core Data Protection. De key ring wordt **automatisch** persistent opgeslagen in de database (`PersistKeysToDbContext`, met een expliciete, stabiele applicatie-discriminator) — dit hoeft niet meer apart geconfigureerd te worden. Dit is bewust zo gebouwd omdat de atomische release-switch (zie hierboven) bij elke deploy een nieuwe content-root-map gebruikt: zonder een database-backed key ring zou dat elke keer de key ring weggooien en alle opgeslagen slave-API-keys onleesbaar maken.
### 3. Database
Migraties op `ApplicationDbContext` (Identity/Core) worden bij het opstarten **automatisch** toegepast (`MigrateCoreDatabase()`), en falen hard (fail-fast) als dat niet lukt — de applicatie start dan bewust niet door. Voor productie-deploys wordt vóór elke deploy een databasebackup genomen; zie de Operations-documentatie van deze feature voor de exacte procedure. Per-module migraties (`Modules.Master`, `Modules.Availability`) worden zoals voorheen automatisch toegepast via `UseModule` (zie "Per-module migraties" hierboven) — daar verandert niets aan.
### 4. Health-check endpoint
`GET /health` geeft alleen **infrastructuur-liveness** aan ("draait het proces en kan het een basale response geven") — géén databasecheck, om te voorkomen dat het endpoint rood kleurt om redenen die niets met "leeft het proces nog" te maken hebben. Dit is expliciet **iets anders** dan `GET /api/v1/Availability/status` (de CMS-eigen aan/uit-schakelaar) of `GET /api/v1/System/capabilities` — een instantie kan gezond zijn en toch bewust uitgeschakeld, en andersom. `/health` staat op de bypass-lijst van `AvailabilityMiddleware`, zodat een uitgeschakelde instantie dit endpoint altijd blijft beantwoorden.