Files
slp-modular-cms/aidlc-docs/features/andreaslop-site-hosting/asf-iis-production-config.md
T
SluijsensandClaude Sonnet 5.5 46eedba199
Continuous Integration / config-sls (pull_request) Successful in 10s
Continuous Integration / config-asf (pull_request) Successful in 8s
Continuous Integration / changes (pull_request) Successful in 19s
Continuous Integration / backend-build (pull_request) Skipped
Continuous Integration / compile-sites (pull_request) Skipped
Continuous Integration / backend-test (pull_request) Skipped
Continuous Integration / vulnerability-scan (pull_request) Skipped
Continuous Integration / frontend-prepare (pull_request) Skipped
Continuous Integration / frontend-build (pull_request) Skipped
Continuous Integration / frontend-test (pull_request) Skipped
Continuous Integration / frontend-lint (pull_request) Skipped
Continuous Integration / publish-sls-test (pull_request) Skipped
Continuous Integration / publish-sls-production (pull_request) Skipped
Continuous Integration / deploy-sls-test (pull_request) Skipped
Continuous Integration / deploy-sls-production (pull_request) Skipped
Continuous Integration / publish-asf-test (pull_request) Skipped
Continuous Integration / deploy-asf-test (pull_request) Skipped
Continuous Integration / smoke-sls-test (pull_request) Skipped
Continuous Integration / smoke-asf-test (pull_request) Skipped
Docs: ASF-productiedatabase heet slopAndreaSlopFotografie (hostervoorvoegsel slop)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-18 21:23:01 +01:00

199 lines
17 KiB
Markdown

# ASF op IIS (MijnHostingPartner): configuratiesleutels, web.config en geheimen
Voorstel (2026-11-18), nog niet uitgevoerd. Er is niets op productie gezet; alles hier wacht op Bryans go. Geschreven voor Bryan, die de omgevingsvariabelen op de hoster instelt. Bronnen: `src/SlpModularCms.Api.AndreaSlopFotografie/appsettings.json`, de Options-klassen in Core en de modules, `docs/release-checklist-productie.md`, `README.md` (E-mail, Rate limiting), `docs/hero-module.md`.
Samenvatting in vier regels:
1. De host leest configuratie in deze volgorde (latere wint): `appsettings.json` (in de release, bevat alleen veilige standaardwaarden) < `appsettings.Production.json` (alleen op de server) < omgevingsvariabelen (web.config) < command line.
2. **Geheimen** (verbindingsstring, JWT-sleutel, SMTP-wachtwoord, Setup-token) in een **alleen-server `appsettings.Production.json`**; **niet-geheime** waarden in het `environmentVariables`-blok van de web.config of ook in dat bestand. Zet een sleutel niet op twee plekken: de omgevingsvariabele wint stilzwijgend.
3. De deploy (FTP) mag `appsettings.Production.json` en de mediamap nooit overschrijven of verwijderen; die zitten niet in het artefact.
4. Een sleutel in JSON schrijf je geneste (`"ConnectionStrings": { "DefaultConnection": ... }`); als omgevingsvariabele met dubbele underscore (`ConnectionStrings__DefaultConnection`). Lijstwaarden als `__0`, `__1`, ...
## 1. Sleutels die de host voor ASF-productie nodig heeft
Legenda: **V** = verplicht (de host start niet of werkt niet zonder), **A** = aanbevolen, **O** = optioneel (standaard is goed). **G** = geheim (alleen in `appsettings.Production.json`, nooit in repo of web.config). Voorbeeldwaarden zijn verzonnen.
### 1a. Omgeving en basis
| Sleutel (als omgevingsvariabele) | | G | Voorbeeld / uitleg |
|---|---|---|---|
| `ASPNETCORE_ENVIRONMENT` | V | nee | `Production` (laadt `appsettings.Production.json`; bepaalt ook de Sentry-omgeving als `Observability__Environment` leeg is). |
| `ConnectionStrings__DefaultConnection` | V | **ja** | `Server=<db-host>;Port=3306;Database=slopAndreaSlopFotografie;Uid=<gebruiker>;Pwd=<wachtwoord>` (MariaDB/MySQL van de hoster). Productie: de database heet `AndreaSlopFotografie` (zonder achtervoegsel, zoals bij SLS), maar de hoster zet het voorvoegsel `slop` ervoor, dus de volledige naam in `Database=` is `slopAndreaSlopFotografie`. De gebruikersnaam kan ook een voorvoegsel krijgen (Bryan controleert de exacte naam in het hostingpaneel; in het voorbeeld staat `<gebruiker>`). Test blijft `AndreaSlopFotografieTest`. Een eigen database, niet die van een andere site, en **niet** de oude WordPress-database `andreaslop` (die wordt niet gebruikt en blijft ongemoeid). Het voorvoegsel `slop` is dat van de hoster; het paneel kan ook een lengtelimiet opleggen: gebruik altijd de volledige naam die het paneel toont, in `Database=` en `Uid=`. De migraties draaien bij de eerste start (zie 4). |
| `JwtSettings__Secret` | V | **ja** | Minstens 32 willekeurige tekens, uniek voor productie (niet de ontwikkelsleutel). Wisselen logt alle ingelogde gebruikers uit. |
| `JwtSettings__Issuer` / `JwtSettings__Audience` | O | nee | Staan in de committed `appsettings.json` (`SlpModularCms` / `SlpModularCmsPortal`); alleen zetten om af te wijken. |
| `JwtSettings__CookieSameSite` | O | nee | Standaard `Strict` (goed: de admin staat op dezelfde site als de API). Niet op `None` zetten. |
| `AllowedHosts` | A | nee | `andreaslop.nl;www.andreaslop.nl` (committed waarde is `*`). |
| `Cors__AllowedOrigins__0` | O | nee | Leeg laten: de admin draait op dezelfde origin (`/admin`). Alleen invullen als de admin elders gehost wordt. |
### 1b. De website (voorgerenderd) en zoekmachines
| Sleutel | | G | Voorbeeld / uitleg |
|---|---|---|---|
| `Website__Mode` | V (staat al goed) | nee | `PrerenderedPages` staat in de committed `appsettings.json`; niet overschrijven. |
| `Website__NoIndex` | V | nee | **`false`** op productie (committed standaard is `true` = geen zoekmachines). Pas zetten op het release-moment, na Bryans go. |
| `Website__PublicBaseUrl` | A | nee | Leeg op productie is toegestaan (de site wordt geserveerd met het adres waarmee hij is gebouwd). Wil je het expliciet: `https://www.andreaslop.nl` (zonder slash). Moet gelijk zijn aan `Website__AuthoredBaseUrl` of die vervangt het. |
| `Website__AuthoredBaseUrl` | O | nee | Het adres dat de websitebuild in pagina's, sitemap en robots schrijft; staat in de committed instellingen. |
| `Website__LogLevel` | O | nee | Standaard `Warning` (productie). `Information` toont ook 301's en 404's: alleen tijdelijk. |
| `Texts__DefaultLanguage` | O | nee | `nl` (standaard). |
### 1c. Mail (uitnodigingen, wachtwoord opnieuw instellen)
Mail staat uit zolang `Email__Smtp__Host` leeg is; dan kopieert de beheerder de link. De host weigert te starten bij een onjuiste, half ingevulde mailconfiguratie (met een melding zonder geheimen).
| Sleutel | | G | Voorbeeld / uitleg |
|---|---|---|---|
| `Email__Smtp__Host` | A (nodig voor mail) | nee | `mail.<hoster>.nl` (zet mail aan). |
| `Email__Smtp__Port` / `Email__Smtp__EnableSsl` | A | nee | `587` / `true` (STARTTLS). |
| `Email__Smtp__Username` | A | **ja** | `no-reply@andreaslop.nl` |
| `Email__Smtp__Password` | A | **ja** | alleen in `appsettings.Production.json` |
| `Email__FromAddress` / `Email__FromName` | A | nee | `no-reply@andreaslop.nl` / `Andrea Slop Fotografie` (SPF/DKIM moeten voor dit adres kloppen). |
| `Email__AllowedFromAddresses__0` | O | nee | Extra afzenderadressen die de eigenaar in de admin mag kiezen. |
| `App__PublicBaseUrl` | V als mail aan staat | nee | `https://www.andreaslop.nl` (https, zonder pad). Gebruikt in de links van de mails. |
| `App__DefaultLanguage` | O | nee | `nl` |
### 1d. Eerste beheerder en toegang
| Sleutel | | G | Voorbeeld / uitleg |
|---|---|---|---|
| `Identity__Setup__Token` | A | **ja** | Minstens 32 willekeurige tekens. Beschermt het aanmaken van de eerste beheerder op een lege database; weghalen zodra die bestaat. Leeg = de setuppagina is niet beveiligd (op internet is dat een risico tot de eerste beheerder er is). |
| `Identity__Invitation__ExpiryHours` | O | nee | `24` (standaard). |
| `RateLimiting__Login__PermitLimit` / `...WindowSeconds` | O | nee | `5` per `60` s per clientadres (standaard). |
| `ForwardedHeaders__KnownProxies__0` | O | nee | Alleen als er een reverse proxy/CDN van de hoster voor IIS staat en het echte bezoekersadres nodig is (rate limiting werkt per adres). Vraag de hoster; leeg = `X-Forwarded-*` wordt genegeerd. Een wildcard (`0.0.0.0`, `::`) laat de host niet starten. |
### 1e. Foto's (Hero en Media)
| Sleutel | | G | Voorbeeld / uitleg |
|---|---|---|---|
| `Media__Directory` | V voor uploads | nee | Een map **buiten de release en buiten de webroot**, bijvoorbeeld `D:\data\andreaslop\media`. Beschrijfbaar voor de identiteit van de application pool. Zonder deze instelling (of bij een niet-beschrijfbare map) staan uploads uit; bestaande foto's blijven werken. De map moet in de back-up zitten. |
| `Media__MaxUploadBytes` / `Media__MaxTotalBytes` | O | nee | 10 MB per foto / 2 GB totaal (standaard). Pas aan als het hostingpakket kleiner is dan 2 GB. |
| `Media__RetentionDays` / `Media__TrashDays` | O | nee | 7 / 7 (standaard). |
| `Media__AutoCleanupUnattached` | O | nee | `false` (standaard): ongebruikte uploads blijven tot iemand ze in de mediabibliotheek verwijdert. |
| `Media__MaxParallelJobs` | A | nee | `2` (standaard); op een kleine gedeelde hosting `1`. |
| `Hero__TextOnlyRegion`, `Hero__TitlePrefix` | O | nee | Voor ASF leeg laten (ASF heeft foto's in de hero). |
| `Hero__MaxPublishedSlides` | O | nee | `50` (standaard). |
Controle na de eerste start: het log toont `Image library Magick.NET self-test passed`. Zo niet, dan zijn uploads uitgezet (de native Magick-bibliotheek moet bij de self-contained win-x64 build zitten).
### 1f. Contactformulier en captcha
| Sleutel | | G | Voorbeeld / uitleg |
|---|---|---|---|
| `Contact__Enabled` | O | nee | **Niet zetten** (standaard `false`) tot Bryan het formulier live wil. Dan nog `Contact__RecipientEmail` en een werkende mailconfiguratie. |
| `Contact__RecipientEmail` | alleen bij Enabled | nee | Adres dat de meldingen krijgt (de admin kan een eigen adres instellen). |
| `Contact__Captcha__Enabled` | O | nee | `false` (standaard); er is geen captcha-aanbieder gekozen. Aanzetten vereist `SiteKey`, `Secret` (**G**), `Region` en laat de host bij foute waarden niet starten. |
| `Contact__RetentionMonths` / `Contact__SpamRetentionDays` | O | nee | 12 / 30 (standaard); moeten kloppen met de privacyverklaring. |
### 1g. Beveiligingsheaders, Sentry en Umami
| Sleutel | | G | Voorbeeld / uitleg |
|---|---|---|---|
| `SecurityHeaders__Enabled` | O | nee | `true` (standaard). De committed instellingen geven de website het `StrictSite`-beleid en laten alleen Umami (`https://analytics.slpsoftware.nl`) en de Sentry-ingest toe. Niet verruimen zonder reden. |
| `SecurityHeaders__AllowedSiteFrameOrigins__0` | O | nee | Alleen als de site een iframe van een derde partij toont (bijv. captcha). Leeg = geen `frame-src`. |
| `Observability__SentryDsn` | A | nee (halfopenbaar) | `https://<sleutel>@o....ingest.de.sentry.io/<project>`. Leeg = geen Sentry, console-logging blijft. Gebruik een eigen Sentry-project voor ASF-productie. |
| `Observability__Environment` | A | nee | `production` (valt anders terug op `ASPNETCORE_ENVIRONMENT`). |
| `Observability__TracesSampleRate` | O | nee | `0.1` (standaard). |
| Umami | n.v.t. | nee | De host en de admin gebruiken geen Umami; alleen de website zelf laadt het script (de CSP staat het toe). Niets in de host-configuratie. |
### 1h. Wat je niet hoeft te zetten
`Availability__*`, `MasterPolling__*`: ASF is geen master/slave-opstelling (alleen Identity, Availability, Offerings, Hero, Media, Contact). `Logging__LogLevel__*`: de committed waarden zijn goed (EF-SQL op `Warning`, zodat er geen e-mailadressen in het log komen); gebruik voor de websitelog `Website__LogLevel`, niet `Logging__LogLevel__SlpModularCms.Website` (een punt in een variabelenaam werkt niet in een omgevingsvariabele). Data Protection-sleutels staan in de database (vast, geen configuratie).
## 2. Sjabloon voor de gepubliceerde web.config
`dotnet publish` (Sdk.Web) maakt zelf een `web.config` met de `aspNetCore`-handler; in de ASF-pijplijn voegen we de standaardinstellingen van de hoster (defaultDocument, headers) daarin samen. De referentiefile van de hoster (alleen defaultDocument, `X-Powered-By`, `httpErrors`) bevat nog geen handler. Voorstel:
```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<location path="." inheritInChildApplications="false">
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
</handlers>
<!-- inprocess: de app draait in de IIS-werkproces (sneller, een proces). Vereist de ASP.NET Core Module
(Hosting Bundle) op de server; vraag de hoster. Valt dat tegen: hostingModel="outofprocess"
(Kestrel achter IIS; dan telt ForwardedHeaders__KnownProxies__0 = 127.0.0.1). -->
<aspNetCore processPath=".\SlpModularCms.Api.AndreaSlopFotografie.exe"
arguments=""
hostingModel="inprocess"
stdoutLogEnabled="true"
stdoutLogFile=".\logs\stdout">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />
<environmentVariable name="Website__NoIndex" value="false" />
<environmentVariable name="Media__Directory" value="D:\data\andreaslop\media" />
<environmentVariable name="App__PublicBaseUrl" value="https://www.andreaslop.nl" />
<environmentVariable name="Observability__Environment" value="production" />
<!-- Geen geheimen hier: die staan in appsettings.Production.json naast de exe. -->
</environmentVariables>
</aspNetCore>
<!-- Uit de standaardfile van de hoster, ongewijzigd overgenomen -->
<directoryBrowse enabled="false" />
<httpProtocol>
<customHeaders>
<remove name="X-Powered-By" />
</customHeaders>
</httpProtocol>
<httpErrors errorMode="DetailedLocalOnly" existingResponse="Auto" />
<!-- Uploadlimiet van IIS (standaard 30 MB) boven de limiet van de hero (10 MB): -->
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" />
</requestFiltering>
</security>
</system.webServer>
</location>
</configuration>
```
Opmerkingen:
- `defaultDocument` van de hoster laat ik weg: de app serveert `/` zelf (voorgerenderde pagina's uit `wwwroot/web`); een `index.html` in de siteroot van IIS zou de handler omzeilen. Staat daar niets, dan is behouden ook onschadelijk.
- De hoster zet `X-Powered-By: ASP.NET`; ik haal de header weg (lekt geen informatie nodig). Wil je de hosterstandaard houden, laat de `remove`/`add` zoals in hun bestand.
- **stdout-log alleen voor de eerste start**: zet `stdoutLogEnabled="false"` na de eerste succesvolle start; de map `logs` moet bestaan en beschrijfbaar zijn. Het log bevat de opstartregels (migraties, Magick-self-test, guard-melding), geen geheimen.
- `processPath` hoort bij de self-contained build (`.exe` naast de web.config). Bij framework-dependent staat daar `dotnet` en `arguments=".\SlpModularCms.Api.AndreaSlopFotografie.dll"`.
- Deploy: een `app_offline.htm` in de siteroot zet de app tijdens het uploaden stil (geen vergrendelde bestanden); verwijderen na afloop.
## 3. Geheimen: waar en hoe
Voorkeur: **server-only `appsettings.Production.json`**, naast de exe, rechten alleen voor de identiteit van de application pool en de beheerder. Voordelen: de FTP-deploy overschrijft de web.config bij elke release (en publiceert alleen wat in het artefact zit), maar dit bestand zit niet in het artefact en blijft staan; het staat niet in de repo en niet in `wwwroot` (wordt nooit geserveerd); lokale wijzigingen zijn zonder herdeploy mogelijk (de host herlaadt het bestand, of recycle de pool).
```json
{
"ConnectionStrings": {
"DefaultConnection": "Server=<db-host>;Port=3306;Database=slopAndreaSlopFotografie;Uid=<gebruiker uit het paneel>;Pwd=<wachtwoord>"
},
"JwtSettings": {
"Secret": "<minstens 32 willekeurige tekens>"
},
"Identity": {
"Setup": { "Token": "<minstens 32 willekeurige tekens, na de eerste beheerder verwijderen>" }
},
"Email": {
"Smtp": { "Host": "mail.<hoster>.nl", "Username": "no-reply@andreaslop.nl", "Password": "<wachtwoord>" }
},
"Observability": {
"SentryDsn": "https://<sleutel>@o<id>.ingest.de.sentry.io/<project>"
}
}
```
Regels:
- Een sleutel staat op **één** plek. Staat hij ook in het `environmentVariables`-blok, dan wint de omgevingsvariabele en lijkt het bestand genegeerd.
- Het bestand wordt **nooit** door de pijplijn gemaakt of vervangen. De pijplijn mag er niet op mirroren (FTP-sync die "extra" bestanden op de server verwijdert, zoals `lftp mirror --delete`, moet `appsettings.Production.json`, `logs/` en de mediamap uitsluiten). Bryan zet het bestand eenmalig met de hand.
- Alternatief als de hoster geen eigen bestanden naast de exe toestaat: omgevingsvariabelen in het IIS-beheer van de site (`Configuration Editor > system.webServer/aspNetCore/environmentVariables` of via het hostingpaneel); die overleven een deploy omdat ze niet in de web.config van het artefact staan. Niet in de gepubliceerde web.config.
- Geen geheimen in de repo, in logs of in dit soort documenten. Draai de sleutels (`JwtSettings__Secret`, SMTP-wachtwoord, databasewachtwoord) bij vermoeden van uitlekken; wijzigen van de JWT-sleutel logt iedereen uit.
## 4. Volgorde bij de eerste start (database)
Een lege productiedatabase (aanmaken in het hostingpaneel als `AndreaSlopFotografie`; de volledige naam wordt `slopAndreaSlopFotografie` door het hostervoorvoegsel; de gebruiker krijgt CREATE/ALTER/INDEX/DROP-rechten voor de migraties; de oude WordPress-database `andreaslop` blijft ongebruikt en wordt niet gekoppeld): de host maakt bij de eerste start alle tabellen (migraties van Core, Identity, Availability, Offerings, Hero, Media, Contact). Geen `HeroImages`-kopie nodig (leeg: de guard laat door). Daarna: setuppagina met `Identity__Setup__Token` (eerste beheerder), `Identity__Setup__Token` weghalen, foto's uploaden of de hero seeden (met Bryans go), `Website__NoIndex=false` op het release-moment. Vooraf: databaseback-up en bij een bestaande database het herstelpunt (zie `production-rollout.md` van de mediabibliotheek).
## 5. Open punten voor Bryan
1. Staat de ASP.NET Core Module (Hosting Bundle) op de server van MijnHostingPartner, en welke `hostingModel` ondersteunen ze? (Bepaalt `inprocess` of `outofprocess`.)
2. Mag er een eigen bestand (`appsettings.Production.json`) naast de exe, buiten de FTP-sync? Zo niet: omgevingsvariabelen via het hostingpaneel.
3. Pad en rechten van `Media__Directory` en grootte van het pakket (2 GB totaal is de standaardgrens van de bibliotheek).
4. Staat er een reverse proxy/CDN van de hoster voor IIS (voor `ForwardedHeaders__KnownProxies__0`)?
5. Welke MariaDB/MySQL-versie, welke gebruikersrechten (CREATE/ALTER voor de migraties) en hoe heet de gebruiker exact (voorvoegsel?) en is er een lengtelimiet? (De database wordt `slopAndreaSlopFotografie`.)