- CmsHostOptions.ResolveWebsiteMode: Website:Mode wint van de code, default SpaFallback, onbekende waarde stopt de host. - ASF: Website:Mode=PrerenderedPages in appsettings.json, Program.cs zonder eigen modus. - SlpModularCms.Api verwijst nu ook naar Offerings en Contact met generieke default-config (Website/Email/App/Contact/RateLimiting). - SmtpFailureTests: '535' als los getal, niet als substring van een willekeurige poort. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
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 voortest.slpsoftware.nl/slpsoftware.nl(CI/CD-cutover vanafSlpModularCms.Api). Host dezelfde modules alsSlpModularCms.Apivia dezelfde gedeeldeCmsHost-compositie (zie hieronder), plus deOfferings- enContact-module. Heeft een eigen, geïsoleerde lokale ontwikkeldatabase — zieappsettings.Development.jsonin dat project.src/SlpModularCms.Api.AndreaSlopFotografie: Derde Client-project voor Andrea Slop Fotografie (testomgevingtest.andreaslop.nl). Host de modulesIdentity,Availability,OfferingsenContact(geenMaster) en serveert de voorgerenderde website uitwwwroot/web/(WebsiteMode.PrerenderedPages) plus de admin met het themaasfop/admin. Lokaal op poort5200, eigen database (appsettings.Development.json). Bijbehorende tests:SlpModularCms.Api.AndreaSlopFotografie.Tests(de pipelinetests daarin hebben net alsApi.Testseen bereikbare MariaDB nodig).src/SlpModularCms.Core: Kern functionaliteiten, data modellen en interfaces. Bevat ookCore/Hosting/CmsHost.cs— de gedeelde service- en pipeline-compositie die elk Client-project (Api,Api.SlpSoftware) vanuit zijn eigen dunneProgram.csaanroept, zodat beide projecten niet uit elkaar kunnen groeien.src/SlpModularCms.Modules.*: Onafhankelijke functionele modules.frontend/: De CMS admin web-UI (Vite + React + TypeScript). Bewust buitensrc/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:
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:
{
"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:
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 eenaccessTokenin de body en eenrefreshTokenin een beveiligdehttpOnlycookie. - Refresh:
POST /api/v1/auth/refresh. Gebruikt derefreshTokencookie om een nieuweaccessTokenenrefreshToken(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:AllowedOriginsworden geaccepteerd. De frontend moet draaien op een van deze origins. - Cookies: De
refreshTokencookie ishttpOnly,SameSite=Stricten 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 wordenX-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
ProblemDetailsstandaard.
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
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): 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 metcredentials. - De
httpOnlyrefreshTokencookie op pad/api/v1/auth(silent refresh bij opstarten). - RFC 9457
ProblemDetailsfoutmeldingen.
Let op: de API-poort in
.env.example(5000) moet overeenkomen met de werkelijke API-poort en deCors:AllowedOriginsconfiguratie van de backend.
Scripts
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):
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:
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:
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.Availabilityis--context AvailabilityDbContextverplicht, omdat de API-startup-project meerdereDbContext-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>.
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:
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:
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:
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): eigenMasterDbContextmet deCmsInstance-entiteit (URL, versleutelde API key, status). BevatCmsInstanceController(/CmsInstances, Owner-only),SlaveApiClient(uitgaande HTTP-calls naar slaves),SlaveStatusController(GET /api/v1/SlaveStatus, laat een slave zijn eigen status ophalen) enIntegrityCheckBackgroundService(periodieke reconciliatie + status-herpush, standaard elk uur). - Slave-extensie (
SlpModularCms.Modules.Availability): eigenMasterRegistration-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 uitgebreideAvailabilityMiddlewaredie zowel de lokale als de master-gate evalueert.
Registratie- en statusflow
- Owner voegt op de Master
/cms-pagina een slave toe met diens URL. - De Master genereert een API key, versleutelt deze (Data Protection) en slaat hem op bij de
CmsInstance. - De Master pusht de registratie naar de slave:
POST /api/v1/master/registermet headerX-Master-Api-Key. - 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):
MasterStatusPollingBackgroundServiceop de slave haalt zelf zijn status op bijGET /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 naarAvailable— een dode of onbereikbare Master mag een slave nooit permanent blokkeren.
Configuratie
Nieuwe sectie MasterModule in appsettings.json (zie ook appsettings.Development.json):
"MasterModule": {
"IntegrityCheckIntervalMinutes": 60,
"HttpTimeoutSeconds": 10,
"MasterUrl": "https://jouw-master-domein"
}
MasterUrlis de publieke URL van déze master-instantie, gebruikt doorIntegrityCheckBackgroundService(buiten een HTTP-requestcontext heeft de background service geenHttpContextom dit uit af te leiden).
Nieuwe sectie MasterPolling (op elke instantie die Modules.Availability laadt — dus ook de slave):
"MasterPolling": {
"PollIntervalSeconds": 30,
"FailOpenAfterMinutes": 5,
"HttpTimeoutSeconds": 5
}
- Heeft geen effect zolang er geen
MasterRegistrationbestaat (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(MasterControlledAvailabilityExceptioninPersistentAvailabilityService.UpdateStatusAsync) — de master-gate kan dus niet per ongeluk of expres lokaal worden omzeild. GET /api/v1/Availability/statusgeeft dit door via het veldisMasterControlled.
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
positiongeldtbottom; een andere waarde geeft400. 204zonder actieve banner; anders200mettitle,text,linkLabel,linkUrl,position(geen planning).- Anoniem, rate limit
offerings-public(standaard 120 per 60 s per clientadres,RateLimiting:OfferingsPublic), antwoord metCache-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.
- Uit tenzij beide schakelaars aan staan: de hostschakelaar
Contact:Enabled(standaardfalsein beideappsettings.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 alsContact:Enabledaan staat. - Publiek:
GET /api/v1/contact-messages/token(tijdtoken, plus eventuele captcha-gegevens) enPOST /api/v1/contact-messages(JSON, headerIdempotency-Keymet een GUID; antwoord202; fouten400inProblemDetails-vorm met veldcodesrequired,tooLong,invalid,expired). - Beheer (
AdminOnly):GET /api/v1/contact-messages,GET/PATCH/DELETE …/{id},POST …/{id}/resend, enGET/PUT /api/v1/contact-settings(schakelaar) metPUT …/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 moetForwardedHeaders__KnownProxies__0gezet 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 omgevingsvariabeleContact__RecipientEmail),Mail:SweepSeconds/MaxAttempts/BackoffMinutes/ClaimMinutes/BatchSize, enCaptcha:Enabled/Provider(friendlycaptcha)/SiteKey/Secret(alleen viaContact__Captcha__Secret)/Region(globalofeu)/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):
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):
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:
dotnet ef database update --project src\SlpModularCms.Core --startup-project src\SlpModularCms.Api.Slave --context ApplicationDbContext
2. Frontend starten
Tegen de master (standaard):
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):
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):
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:
- Log in op de master-frontend (
http://localhost:5173) en ga naar de/cms-pagina. - Gebruik de bestaande "Add CMS Instance"-dialoog om de lokale slave toe te voegen met URL
https://localhost:7222. - 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 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 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):
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 moetX-Forwarded-ForenX-Forwarded-Protodoorgeven -
Identity__Setup__Token— optioneel beschermingstoken voor het aanmaken van de eerste beheerder (POST /api/v1/Setup/ownerverwacht dan de headerX-Setup-Token;GET /api/v1/Setup/statusmeldttokenRequired). Minstens 32 willekeurige tekens; alleen-witruimte laat de host falen bij opstarten. Beide setup-endpoints vallen onder delogin-limiter en een geweigerd token wordt gelogd als beveiligingsgebeurtenissetup_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/adminen/api/v1mag toestaan (bijv. de Umami-scripthost en Sentry's ingest-endpoint). Zieappsettings.json → SecurityHeadersvoor de volledige optiesvorm; een onbekendePathPolicies-policy-naam laat de applicatie bij opstarten falen, niet pas bij de eerste request -
Voorgerenderde website (
WebsiteMode.PrerenderedPages) — een client kiest dit in zijnProgram.csviaCmsHostOptions(standaardSpaFallback: alles blijft zoals het was). Instellingen voor deze modus:Website__NoIndex=true(testinstantie:X-Robots-Tagplusrobots.txtmetDisallow: /),SecurityHeaders__DefaultPolicy=StrictSitemetSecurityHeaders__AllowedSiteScriptOrigins__0,SecurityHeaders__AllowedSiteConnectOrigins__0, ... (alleen gebruikt doorStrictSite). Logging van de website (301's en 404's opInformation) gaat via de logger-categorieSlpModularCms.Website: zet per omgevingWebsite__LogLevel(testInformation, standaard en productieWarning; leeg =Logging:LogLevelbeslist). Gebruik nietLogging__LogLevel__SlpModularCms.Websitein een systemd-EnvironmentFile: een variabelenaam met een punt wordt daar genegeerd. Gedrag per pad staat inWEBSITE_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.