E-mailfeature Operations: deployment, monitoring, productiegereedheid; configuratiefouten als Error-log
Mislukte mails door een configuratieprobleem (auth_failed, rejected_sender, tls_failed, not_configured) worden als Error gelogd zodat Sentry een alert stuurt; timeouts en ontvangerproblemen blijven Warning. Documentatie: uitrol per host met de hand in shared/env, rollback, monitoringplan, checklist; ASF-productie op IIS als open punt voor een latere feature. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
+25
@@ -0,0 +1,25 @@
|
||||
# Deployment instructions - turning mail on for a host
|
||||
|
||||
For whoever manages the host (Pi-Main). Do this per host and per environment; credentials never go into the repository, a chat or a ticket.
|
||||
|
||||
## Before you start
|
||||
- The release containing the mail feature is already deployed (a host without mail settings behaves exactly as before).
|
||||
- You have: the SMTP host and port, the account (username, password) that may send as the chosen sender address, the public https address of the site (no path).
|
||||
|
||||
## Steps
|
||||
1. Open the host's environment file (Pi: `~/apps/<site>/<env>/shared/env`, mode 600).
|
||||
2. Add, in one go (the order inside the file does not matter, but set `App__PublicBaseUrl` together with the host or the host starts with mail off):
|
||||
- `App__PublicBaseUrl=https://<site address>`
|
||||
- `Email__Smtp__Host=<smtp host>`, `Email__Smtp__Port=587`, `Email__Smtp__EnableSsl=true`
|
||||
- `Email__Smtp__Username=<account>`, `Email__Smtp__Password=<password>`
|
||||
- ASF: `Email__FromAddress=no-reply@andreaslop.nl`, `Email__AllowedFromAddresses__0=no-reply@andreaslop.nl`, `Email__FromName=Andrea Slop Fotografie` (SlpSoftware: nothing more is needed)
|
||||
3. Restart the unit (Pi: `systemctl --user restart <unit>`).
|
||||
4. Read the journal (Pi: `journalctl --user -u <unit> -n 50`):
|
||||
- success: a line `mail_status enabled=true smtp_host=... starttls=true default_from_domain=...`;
|
||||
- a line `mail_configuration_invalid ... <setting names>` (Error): mail stays OFF, the site runs; fix the named settings and restart.
|
||||
5. `curl https://<site>/api/v1/System/capabilities` shows `"emailEnabled":true`.
|
||||
6. Real test (Bryan): in the admin invite a mailbox of yours (Gmail and Outlook, see the readiness checklist); the dialog says "mail sent" or names the reason. Also try "Wachtwoord vergeten?" on the login page.
|
||||
7. If a mail is refused, the journal line `identity_mail_failed code=... detail=... phase=... timings=...` tells what happened (`rejected_sender`: the account may not send as that address; `auth_failed`: wrong credentials; `tls_failed`: STARTTLS problem; `timeout_*`: slow or blocked server). Settings to change: see the infrastructure design.
|
||||
|
||||
## Changing or removing mail later
|
||||
Edit the same file and restart. To switch mail off: delete `Email__Smtp__Host` (the copy-link flow keeps working) and restart.
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
# 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`.
|
||||
|
||||
## 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.
|
||||
+9
@@ -0,0 +1,9 @@
|
||||
# Rollback plan - identity-email-notifications
|
||||
|
||||
Decision (Q7 A).
|
||||
|
||||
1. **Switch mail off quickly** (no code change): remove `Email__Smtp__Host` from the host's environment file and restart the unit. The admin hides every mail feature (`emailEnabled=false`), invitations work by copying the link, the two anonymous endpoints answer 404. Nothing is lost.
|
||||
2. **Bad release**: use the existing previous-release switch of the deploy (re-point `current` to the previous release and restart; see the andreaslop-site-hosting rollback plan for the Pi). The three database changes of this feature (`SiteSettings` table, `Users.PreferredLanguage`, `Invitations.Language`) are additive and nullable; the previous code simply ignores them, so no database change is needed to go back.
|
||||
3. **After a rollback of the code**: access tokens issued by the newer release carry a security-stamp claim that the old code ignores; they keep working. Tokens issued by the old code lack the claim and are refused once by a newer release (the silent refresh fixes that).
|
||||
4. A documented way to drop the new columns and table is deliberately not part of the plan (Bryan chose option A); it would only be needed for a full restore.
|
||||
5. IIS (later, ASF production): the same two switches exist in another form (remove the variable and recycle the app pool; keep the previous release folder and switch the physical path).
|
||||
Reference in New Issue
Block a user