Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
21 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=<host>;Port=<poort>;Database=57409_andreaslopfotografie;User=57409_andreaslopfotografie;Password=<wachtwoord>;SslMode=Required;Default Command Timeout=120; (externe MariaDB van de hoster, niet localhost; adres en poort uit het paneel, hier bewust als <host> en <poort> en nooit in de repo; zie 4a voor SslMode en de timeouts). Productie: het hostingpaneel heeft database en gebruiker aangemaakt als 57409_andreaslopfotografie (voorvoegsel 57409_ van de hoster, alles kleine letters); neem die naam letterlijk over in Database= en Uid= (let op hoofdlettergevoeligheid: op de hoster kan de naam hoofdlettergevoelig zijn). 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 paneel kan ook een lengtelimiet opleggen. 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=<host>;Port=<poort>;Database=57409_andreaslopfotografie;User=57409_andreaslopfotografie;Password=<wachtwoord>;SslMode=Required;Default Command Timeout=120;"
},
"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 (door het hostingpaneel aangemaakt als 57409_andreaslopfotografie, met gebruiker 57409_andreaslopfotografie; de namen letterlijk overnemen, alles kleine letters; de gebruiker heeft 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).
4a. De externe database: verbinding, TLS, rechten en gedrag bij een trage of onbereikbare server
Gecontroleerd tegen de code van de host (2026-11-18):
- Formaat. De host gebruikt de Oracle-provider (
MySql.EntityFrameworkCore,UseMySQL) metMySql.Data9.7, niet Pomelo/MySqlConnector. Getest met de connection-string-builder van die assembly:Server,Port,Database,User(synoniem vanUid) enPassword(synoniem vanPwd) worden herkend. Het formaat van Bryan werkt dus;User=/Password=ofUid=/Pwd=is hetzelfde. - TLS (
SslMode). Het verkeer gaat over het internet naar een extern adres; zonder TLS staan het wachtwoord-handshake en alle gegevens onversleuteld op de lijn. De standaard van de provider isSslMode=Preferred(TLS als de server het aanbiedt, anders stilzwijgend ongeversleuteld, en dus te dwingen terug te vallen). Aanbeveling:SslMode=Requiredin de connection string zetten. Werkt de eerste start dan niet ("SSL Connection error" of een handshake-fout in het log), vraag de hoster of de MariaDB-server TLS aanbiedt; pas als die dat niet kan, tijdelijkPreferredgebruiken en dat als open risico bij Bryan neerleggen.VerifyCA/VerifyFullkan alleen met het CA-bestand van de hoster (SslCa=<pad>); niet nodig voor de eerste start. - Toegang van buiten. Een externe MariaDB laat vaak alleen toegestane bronadressen toe: het uitgaande IP-adres van de webserver (IIS) moet in het paneel zijn toegestaan. Ontwikkel- en testmachines komen er niet bij tenzij ze ook zijn toegestaan; test niet met de productiegegevens vanaf een laptop.
- Rechten. De migraties van Core, Identity, Availability, Offerings, Hero, Media en Contact maken en wijzigen tabellen, indexen en (bij de Hero-migraties) verwijderen een kolom of tabel. De gebruiker heeft op deze database minstens SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP en REFERENCES nodig; de standaardgebruiker van een hostingpaneel heeft alle rechten op zijn eigen database. Controle voor de eerste start:
SHOW GRANTS FOR CURRENT_USER();(vanuit het paneel of een toegestane client). De tabel__EFMigrationsHistorywordt zelf aangemaakt. - Timeouts. Standaard wacht de provider 15 seconden op een verbinding (
Connection Timeout) en 30 seconden per opdracht (Default Command Timeout). Over een externe verbinding kan een DDL-opdracht (bijvoorbeeld een migratie met een grote tabel) langer duren; daaromDefault Command Timeout=120in de voorbeeld-string. De Hero-migratie die de oude tabel verwijdert, duurde op test ongeveer 24 seconden. - Bij start. De Core-migratie probeert het vijf keer (
DatabaseMigrationExtensions: wachttijden 2, 4, 6 en 8 seconden, elke poging maximaal 15 seconden verbindingstijd, dus ruim een minuut bij een onbereikbare server). Daarna logt de host een Critical-melding zonder wachtwoord of connection string (en stuurt die naar Sentry als die aan staat) en start het proces niet; IIS toont dan een 500.30 (de app kon niet starten). De reden staat in het stdout-logbestand (stdoutLogEnabled="true", zie de web.config). Een verkeerd wachtwoord of onbekende gebruiker telt als een verbindingsfout en geeft hetzelfde resultaat. - Let op, andere modules. De migraties van de overige modules (Identity, Availability, Offerings, Hero, Media, Contact) lopen na die van Core, elk in de eigen module. Een fout daar wordt als
Errorgelogd ("Fout bij het activeren van module ...") en de applicatie draait dan door zonder de tabellen van die module (behalve bij de bewuste stopmelding van de Hero-controle vóór het verwijderen vanHeroImages, die de start wel stopt). Controleer na de eerste start het stdout-log op die regel en controleer/api/v1/System/capabilities. - Wachtwoord. Alleen in
appsettings.Production.json(zie 3); het adres en de poort staan niet in de repo of deze doc.
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 en welke gebruikersrechten (CREATE/ALTER voor de migraties) heeft de gebruiker
57409_andreaslopfotografieprecies, en is de naam hoofdlettergevoelig op de server? (Database en gebruiker:57409_andreaslopfotografie, letterlijk uit het paneel.)