17 KiB
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:
- 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. - Geheimen (verbindingsstring, JWT-sleutel, SMTP-wachtwoord, Setup-token) in een alleen-server
appsettings.Production.json; niet-geheime waarden in hetenvironmentVariables-blok van de web.config of ook in dat bestand. Zet een sleutel niet op twee plekken: de omgevingsvariabele wint stilzwijgend. - De deploy (FTP) mag
appsettings.Production.jsonen de mediamap nooit overschrijven of verwijderen; die zitten niet in het artefact. - 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=AndreaSlopFotografie;Uid=AndreaSlopFotografie;Pwd=<wachtwoord> (MariaDB/MySQL van de hoster). Productie: database en gebruiker AndreaSlopFotografie (zonder achtervoegsel, zoals bij SLS); 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 hostingpaneel kan een voorvoegsel (bijvoorbeeld <account>_AndreaSlopFotografie) of een lengtelimiet opleggen voor database- en gebruikersnamen: gebruik dan de 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 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:
defaultDocumentvan de hoster laat ik weg: de app serveert/zelf (voorgerenderde pagina's uitwwwroot/web); eenindex.htmlin 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 deremove/addzoals in hun bestand. - stdout-log alleen voor de eerste start: zet
stdoutLogEnabled="false"na de eerste succesvolle start; de maplogsmoet bestaan en beschrijfbaar zijn. Het log bevat de opstartregels (migraties, Magick-self-test, guard-melding), geen geheimen. processPathhoort bij de self-contained build (.exenaast de web.config). Bij framework-dependent staat daardotnetenarguments=".\SlpModularCms.Api.AndreaSlopFotografie.dll".- Deploy: een
app_offline.htmin 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).
{
"ConnectionStrings": {
"DefaultConnection": "Server=<db-host>;Port=3306;Database=AndreaSlopFotografie;Uid=AndreaSlopFotografie;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, moetappsettings.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/environmentVariablesof 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 AndreaSlopFotografie (aanmaken in het hostingpaneel, met gebruiker AndreaSlopFotografie en 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
- Staat de ASP.NET Core Module (Hosting Bundle) op de server van MijnHostingPartner, en welke
hostingModelondersteunen ze? (Bepaaltinprocessofoutofprocess.) - Mag er een eigen bestand (
appsettings.Production.json) naast de exe, buiten de FTP-sync? Zo niet: omgevingsvariabelen via het hostingpaneel. - Pad en rechten van
Media__Directoryen grootte van het pakket (2 GB totaal is de standaardgrens van de bibliotheek). - Staat er een reverse proxy/CDN van de hoster voor IIS (voor
ForwardedHeaders__KnownProxies__0)? - Welke MariaDB/MySQL-versie, welke gebruikersrechten (CREATE/ALTER voor de migraties) en legt het hostingpaneel een voorvoegsel of lengtelimiet op voor de namen
AndreaSlopFotografie?