Files
slp-modular-cms/aidlc-docs/features/identity-email-notifications/construction/mail-foundation/infrastructure-design/infrastructure-design.md
T
SluijsensandClaude Sonnet 5.5 bd9790819d Halve of foute mailconfiguratie: host start, mail uit, een duidelijke Error-logregel
Eén bron (IMailAvailability) bepaalt of mail aan staat: SMTP-host gezet EN de hele mailconfiguratie geldig.
Anders start de host gewoon, gebruikt de Null-verzender, meldt emailEnabled=false en logt eenmalig
mail_configuration_invalid met de namen van de ontbrekende of ongeldige instellingen (nooit waarden of
geheimen). Getest: halve config, elke soort fout, geen geheim in het log, volledige config werkt als
voorheen, geen mailinstelling geeft geen enkele waarschuwing, alle verbruikers zien mail als uit.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-08 20:51:41 +01:00

6.2 KiB

Infrastructure design - U1 mail-foundation

Configuration keys (per environment, on the host)

Key Where Example / note
Email__Smtp__Host shared/env mail.slpsoftware.nl (the SMTP host SimpleDeckApp uses in production, per Bryan). Setting it switches mail ON.
Email__Smtp__Port shared/env 587
Email__Smtp__EnableSsl shared/env true (STARTTLS)
Email__Smtp__Username, Email__Smtp__Password shared/env (mode 600) secrets, never committed, never in messages or logs
App__PublicBaseUrl shared/env https://test.andreaslop.nl (https, no path)
App__DefaultLanguage optional nl (default) or en
Email__FromAddress, Email__FromName committed default or env no-reply@slpsoftware.nl / site name (SimpleDeckApp's committed default)
Email__AllowedFromAddresses__0..n env extra sender addresses a site may choose in its settings; empty = only FromAddress
Email__LogoUrl, Email__BrandColor committed (ASF) or env /admin/brand-logo-on-light.png, #5f6a58

Start-up validation refuses a broken mail configuration (when a host is set) with a message that never contains the credentials. Without a host nothing changes.

Local development

smtp4dev (already installed) on localhost:25: Email__Smtp__Host=localhost, Email__Smtp__Port=25, Email__Smtp__EnableSsl=false, no username, App__PublicBaseUrl=http://localhost:5200 (http is accepted for loopback only).

ASF test host (Operations will do it, needs Bryan's go for the real test mail)

  1. Add the keys above to shared/env of andreaslopfotografie-test (mode 600 stays), restart the unit.
  2. Email__FromAddress stays no-reply@slpsoftware.nl (the SMTP service's own domain). A sender on @andreaslop.nl only after the check below.
  3. One real test mail to an address of Bryan before approval.

Sender-domain alignment (production checklist item)

From: domain, SPF and DKIM must agree with the SMTP service that actually sends:

  • SPF of the From: domain must authorise the sending service (today both slpsoftware.nl and andreaslop.nl publish v=spf1 a mx include:smtp.spf.ziggo.nl ~all).
  • That service must DKIM-sign for the From: domain (a dkim._domainkey record exists for both domains; whether the service signs with it is not visible from outside).
  • mail.slpsoftware.nl will deliver @andreaslop.nl mail properly only if it may send/sign for that domain. DMARC is p=none today (monitoring only).
  • Therefore the sender list is an allowlist: add an @andreaslop.nl address to Email__AllowedFromAddresses only after this is confirmed.

No other infrastructure

No new service, port, queue or storage. One additive table (SiteSettings) in the existing database.

Per-host SMTP server (update 2026-11-08, from Bryan via "CMS & API")

The SMTP settings are per host (all in that host's shared/env), so each site can use its own mail server:

Site SMTP host Sender domain Status
SlpSoftware mail.slpsoftware.nl (the host SimpleDeckApp uses) @slpsoftware.nl as before
ASF (test, later production) probably mail.andreaslop.nl (not mail.slpsoftware.nl) @andreaslop.nl to be confirmed

Read-only checks done from the developer PC (by "CMS & API"): mail.andreaslop.nl and andreaslop.nl both resolve to 217.121.250.215; the MX of andreaslop.nl is mail.andreaslop.nl (preference 10); TCP 587 is reachable. This fits the published SPF (a mx): a mail sent by that server for @andreaslop.nl is SPF-aligned, which the earlier plan (mail.slpsoftware.nl for ASF) would not have been.

Open points (Operations plan, no code needed):

  1. Which mailbox/account on mail.andreaslop.nl is used, and whether it may send with no-reply@andreaslop.nl (or another address) as From. Then ASF sets Email__FromAddress and Email__AllowedFromAddresses__n accordingly (the committed ASF default no-reply@slpsoftware.nl is only a placeholder until then). SlpSoftware keeps mail.slpsoftware.nl.
  2. Port and TLS: not yet confirmed that the server offers STARTTLS on 587 (Email__Smtp__EnableSsl=true); if it needs implicit TLS (465) or none, the sender must be adapted (it supports STARTTLS or plain today) and a plain connection would not be acceptable beyond a private network.
  3. DKIM: a dkim._domainkey.andreaslop.nl record exists; confirm the server signs with that key. DMARC is p=none (monitoring only).
  4. Credentials for that account go into the ASF test unit's shared/env by whoever manages the host (not by this feature's code or by chat).

Release notes for the host manager (required environment variables per release)

  • This release adds NO required environment variable. A host without any mail setting starts exactly as before; this is tested for every deployed host configuration (master, slave, SlpSoftware, ASF).
  • Mail is switched on only by setting Email__Smtp__Host, and it only turns ON when the whole mail configuration is valid: App__PublicBaseUrl (https, no path), Email__FromAddress/Email__FromName (committed defaults), Email__Smtp__Username together with Email__Smtp__Password, and sane port, timeout, colour and logo values. A half-finished or wrong mail configuration never stops the host from starting (decided by Bryan after the 2026-11-08 incident): the host starts with mail OFF (emailEnabled=false, all mail UI hidden, the copy-link flow keeps working) and logs ONE Error line, mail_configuration_invalid, that names each missing or invalid setting (names only, never values or secrets; Sentry sees it). Check the log after changing mail settings. Set App__PublicBaseUrl together with Email__Smtp__Host.
  • Optional: Identity__Invitation__ExpiryHours (24), Identity__PasswordReset__TokenLifetimeMinutes (60), Identity__PasswordReset__CooldownMinutes (5), App__DefaultLanguage (nl), Email__AllowedFromAddresses__0..n, Website__LogLevel.
  • Incident 2026-11-08: ASF test returned 502 after a restart because Email__Smtp__Host was set but App__PublicBaseUrl was not (the start-up validation at that time refused a half-configured mail setup). Not a deploy without mail configuration. Since changed: the soft behaviour above.