Files
slp-modular-cms/aidlc-docs/features/identity-email-notifications/operations/deployment/deployment-plan.md
T

5.2 KiB

Deployment plan - identity-email-notifications

Decisions (Operations questions, answered by Bryan via "CMS & API"): Q1 A, Q2 A (with the ASF production exception below), Q3 A, Q7 A.

Method

The code ships through the existing Gitea Actions pipeline (deploy_asf_test, deploy_test; production only with its own approval). Nothing in the workflow changes. The mail settings are NOT part of the deploy: Pi-Main sets them by hand in the host's shared/env (mode 600), because they contain credentials.

Order

  1. ASF test (code live; mail settings in shared/env, real test mail pending).
  2. SlpSoftware test (code live since run 625/626; mail still off until its shared/env has the settings).
  3. SlpSoftware production, only after steps 1 and 2 are accepted and with Bryan's separate approval.
  4. ASF production is not part of this feature: it does not exist yet and will run on an IIS server instead of a Raspberry Pi. It becomes its own piece of work (see "Open point: ASF production on IIS" below).

Per-host mail settings (all in that host's environment)

Host Email__Smtp__Host Sender Notes
ASF test mail.andreaslop.nl, port 587, EnableSsl=true no-reply@andreaslop.nl in Email__FromAddress and Email__AllowedFromAddresses__0 account on that server created by Bryan; TLS mode (STARTTLS on 587) to be confirmed by the first real test mail
SlpSoftware test mail.slpsoftware.nl, 587, EnableSsl=true default no-reply@slpsoftware.nl (no variable needed) credentials of the account that may send as that address
SlpSoftware production same server as test same own environment, own App__PublicBaseUrl

Common: Email__Smtp__Username, Email__Smtp__Password, App__PublicBaseUrl (https, no path, per environment), optional Email__Smtp__TimeoutSeconds (default 10 per step), Email__FromName. Full list: construction/mail-foundation/infrastructure-design/infrastructure-design.md.

Master host: MasterModule__MasterUrl is required (test and production)

On every host that runs the master module (SlpSoftware test, SlpSoftware production), set MasterModule__MasterUrl to the public address of that master: https, no path, e.g. https://master.example.com. The shipped appsettings.json carries only a placeholder (<public-url-of-this-master-instance>).

  • Why: the hourly integrity check (and the one at start-up) runs without a request, so it cannot derive the address from the request and uses this setting. With the placeholder it used to re-register the slaves with the placeholder, after which a slave could not poll the master any more (master_poll_failed). Now a missing or unusable value makes the master log MasterModule:MasterUrl is not an absolute http(s) address and skip those background checks; nothing is overwritten.
  • Slaves (ASF test, later ASF production) need no such variable: they store the address the master registers. A slave refuses an unusable address (400 invalid_master_url) and the poller logs invalid_master_url.
  • Recovery of a slave that holds a bad address: set the variable on the master and restart it; the start-up check re-registers the slave. A changed variable needs a restart.

Open point: ASF production on IIS (decided 2026-11-09, not designed here)

Everything in this feature's and the andreaslop-site-hosting documents that talks about the host assumes the Raspberry Pi: a systemd user unit (andreaslopfotografie-test), an EnvironmentFile named shared/env (mode 600, readable only by the service user), journalctl for logs, systemctl --user restart after a change, deploy-scp.yaml (scp + symlink current + restart), a reverse-proxy Pi in front, and Linux paths. For an IIS host these assumptions need an answer in the later ASF-production feature (listed, NOT worked out now):

  • Environment variables: the same variable names work (double underscore), but are set in web.config (<aspNetCore><environmentVariables>), as machine-level variables or per app pool, not in shared/env. Secrets: no file mode 600, so decide where the SMTP credentials live (ACL-protected web.config section or machine variables, never in the repository) and who may read them.
  • Restart: an app pool recycle or app_offline.htm instead of systemctl restart; a changed variable needs a recycle.
  • Logs: stdout logging to a file or the Windows event log instead of journalctl; the mail_status, mail_configuration_invalid and identity_mail_failed lines must be reachable there (and Sentry keeps working as is).
  • Deployment: the scp-plus-symlink workflow does not fit; another deploy path is needed (Web Deploy, or file copy into a release folder with a physical-path switch), with the same previous-release rollback idea.
  • Hosting model: ASP.NET Core module (in-process or out-of-process), the .NET runtime on the server, HTTPS binding and certificate on IIS itself (no reverse-proxy Pi), ForwardedHeaders__KnownProxies probably different or unnecessary, ASPNETCORE_ENVIRONMENT.
  • Database and mail server: where MariaDB lives for that host, and whether mail.andreaslop.nl is reachable from the IIS server (firewall, port 587).
  • Health check: the /health URL check of the workflow is fine; the way it is reached changes with the new hostname.