Files
slp-modular-cms/aidlc-docs/features/andreaslop-site-hosting/asf-iis-production-config.md
T

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:

  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=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:

  • 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).

{
  "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, 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 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

  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 legt het hostingpaneel een voorvoegsel of lengtelimiet op voor de namen AndreaSlopFotografie?