From 87fa0a4381eb4c7188b1d022614e8e8691715e6b Mon Sep 17 00:00:00 2001 From: Mix Date: Mon, 12 Oct 2026 15:45:06 +0300 Subject: [PATCH] design: notifications on Account, Server > Settings and Server > Health Accepted by the owner on 2026-10-12 from screenshots, after two changes of his: DKIM for the server's own name as well as SPF ("we need the best deliverability for these messages"), and the records themselves under Settings with only their state on Health. - account: a checkbox "Send me notifications" in the Profile box, under the e-mail it writes to. No box of its own, no choice per event. - settings: box 03 Notifications with the instance switch; box 04 Notification mail with the two DNS records of the server's own name, DKIM and SPF, drawn with the record component of a domain's DNS page. Sending rate limits move to the left column as box 02. - health: card 06 Notification mail - the state of each record and a link to Settings - beside Configuration, now 07, each half the width. - help: a Notifications topic (what is sent, when, to whom, what makes it arrive); Settings and Your account each gain a clause. outlines.json rewritten with check.py --write: the structure of settings and health changed. build.py: 35 pages; check.py: 32 screens, 52 sp- classes, 0 violations. The plan records both of his changes; step 1 of 10. Co-Authored-By: Claude Opus 5.5 --- docs/assets/panel-redesign/panel/account.html | 2 + docs/assets/panel-redesign/panel/health.html | 29 +++++++++++--- docs/assets/panel-redesign/panel/help.html | 6 ++- .../assets/panel-redesign/panel/outlines.json | 23 +++++++++-- .../assets/panel-redesign/panel/settings.html | 39 ++++++++++++++++++- .../panel-redesign/panel/src/account.html | 2 + .../panel-redesign/panel/src/health.html | 29 +++++++++++--- .../assets/panel-redesign/panel/src/help.html | 6 ++- .../panel-redesign/panel/src/settings.html | 39 ++++++++++++++++++- docs/plans/panel-notifications.md | 23 ++++++++--- docs/roadmap.md | 2 +- 11 files changed, 172 insertions(+), 28 deletions(-) diff --git a/docs/assets/panel-redesign/panel/account.html b/docs/assets/panel-redesign/panel/account.html index 464cb49..5e22664 100644 --- a/docs/assets/panel-redesign/panel/account.html +++ b/docs/assets/panel-redesign/panel/account.html @@ -82,6 +82,8 @@

Your own address. A domain's report address can be filled with it from Domain settings.

+
+

To this address, when something needs you: a DNS record of a domain stops matching, a rate limit refuses mail, the TLS certificate is about to expire, a message has waited in the queue for three days. What is sent and when

diff --git a/docs/assets/panel-redesign/panel/health.html b/docs/assets/panel-redesign/panel/health.html index e64d63e..4bced2b 100644 --- a/docs/assets/panel-redesign/panel/health.html +++ b/docs/assets/panel-redesign/panel/health.html @@ -145,11 +145,30 @@ -
-
06

Configuration

Safe to run at any time
-
-

Regenerates the OpenDKIM and Postfix configuration from the database and reloads both daemons. Use it after editing the files by hand, after restoring a backup, or when the running configuration looks out of step with the domain and application lists. It does not touch the queue or the TLS certificate.

-
+
+
+
+
06

Notification mail

warn
+
+ + + + + +
RecordState
DKIM
sp2026._domainkey.mail.example.org		published
SPF
mail.example.org		missing
+
+

Sent from postmaster@mail.example.org. What to publish is under Settings.

+
+
+
+
+
+
07

Configuration

Safe to run at any time
+
+

Regenerates the OpenDKIM and Postfix configuration from the database and reloads both daemons. Use it after editing the files by hand, after restoring a backup, or when the running configuration looks out of step with the domain and application lists. It does not touch the queue or the TLS certificate.

+
+
+
diff --git a/docs/assets/panel-redesign/panel/help.html b/docs/assets/panel-redesign/panel/help.html index 7786bcc..9d84dda 100644 --- a/docs/assets/panel-redesign/panel/help.html +++ b/docs/assets/panel-redesign/panel/help.html @@ -105,6 +105,7 @@
  • Backup and moving a domain
  • Users and roles
  • Settings
    • +
  • Notifications

    • Account

      @@ -141,11 +142,12 @@
      04

      Server

      Backup and moving a domain

      Full backup downloads one archive of the whole instance: data/ (the database, DKIM keys and application credentials), docker-compose.yml, .env and certs/. The Postfix queue is not in it. The backup is taken while the server is running, and Postfix keeps moving messages through the queue, so a copy could hold a message twice or miss it; mail still waiting for delivery is therefore not carried over, and a restored server starts with an empty queue. To keep the queue, stop the container and archive the project directory instead. The private key in certs/ has to be readable by the panel: give it to group 998 on the host (chgrp 998, chmod 640). Until then the panel refuses to make a backup and names the file, rather than hand over an archive without the key. It holds secrets, so leave Encrypt with a password ticked: the file is sealed as .spbk, the password is not stored, and without it nothing can be recovered. To restore, unpack it into an empty project directory (decrypt a .spbk first with selfpost-backup -decrypt) and start the same SelfPost version that made it; the panel refuses data from another version. The reverse-proxy configuration and mail.log are not included. One domain moves on its own: Export domain on its settings page writes a .json (or encrypted .spde) with its DKIM key and its applications' passwords, and Import a domain here reads it into another instance, so the published DNS needs no change.

      Users and roles

      The two roles are a reach, not a rank: every user is an administrator and signs in with a username and password. Global reaches the whole server — Overview, Server, the queue and every domain — and is the only role that adds or deletes domains and users. Domain reaches only the domains assigned to it, outbound and inbound separately (the same name on both lists is two assignments); All includes domains added later, and a domain user needs at least one domain or All on either list. The only global user cannot be demoted or deleted, and you cannot delete the account you are signed in with. A new password set here signs that user out of their other sessions.

      -

      Settings

      Settings holds what is true of the whole instance. Log retention is how many days the Outbound log keeps its rows, from 7 to 365 and 90 by default; a sweep every six hours deletes older ones, and it is the main driver of how fast /data grows. With the inbound relay on there is a second number, for the Inbound log, with the same range. It does not change the rotation of mail.log, which is daily with about two weeks kept. The sending rate limit shown under it is level 1, the per-client-IP ceiling set in .env: changing it needs a restart, and no level-2 limit can exceed it.

      +

      Settings

      Settings holds what is true of the whole instance. Log retention is how many days the Outbound log keeps its rows, from 7 to 365 and 90 by default; a sweep every six hours deletes older ones, and it is the main driver of how fast /data grows. With the inbound relay on there is a second number, for the Inbound log, with the same range. It does not change the rotation of mail.log, which is daily with about two weeks kept. The sending rate limit shown under it is level 1, the per-client-IP ceiling set in .env: changing it needs a restart, and no level-2 limit can exceed it. Notifications are turned on or off here for everyone.

      +

      Notifications

      The panel writes to its users when something needs them, from postmaster@ the server's hostname. Four things are reported. A sending domain's SPF, DKIM or DMARC record stops matching: sent once two hourly checks in a row have found it so, and once more when the record matches again. A level-2 rate limit refuses mail: sent at the first refusal, then at most once a day for the same limit. The TLS certificate is 14 days from expiry, and again at 3 days if it is still the same certificate. A message has waited in the queue for more than three days, with one more message when none is left. A global user is told all of it; a domain administrator is told about the DNS records and limits of their own domains.

      Each user turns notifications on or off under Account and needs an e-mail there; Server › Settings turns them off for everyone. They are the panel's own mail: not rows of the Outbound log, and not counted against any limit.

      For that mail to arrive, the server's own name needs two DNS records of its own, as each of your domains does: a DKIM key, which the panel generates and signs notifications with, and an SPF record, v=spf1 a -all. Server › Settings gives both with the values to publish, and Server › Health shows whether they are in place. Without them notifications are still sent, and a receiver may file them as spam. Mail of your domains does not depend on either.

    05

    Account

    -

    Your account

    Account is your own, whatever your role: your username and e-mail, and your password. Changing the password signs out every other session of this account and keeps the one you are using; applications have their own logins and are not affected.

    +

    Your account

    Account is your own, whatever your role: your username and e-mail, whether the panel sends you notifications, and your password. Changing the password signs out every other session of this account and keeps the one you are using; applications have their own logins and are not affected.

    diff --git a/docs/assets/panel-redesign/panel/outlines.json b/docs/assets/panel-redesign/panel/outlines.json index bdda949..4b9607f 100644 --- a/docs/assets/panel-redesign/panel/outlines.json +++ b/docs/assets/panel-redesign/panel/outlines.json @@ -108,7 +108,20 @@ } ] }, - "box[Configuration]:body" + { + "columns": [ + { + "is-6": [ + "box[Notification mail]:table+body" + ] + }, + { + "is-6": [ + "box[Configuration]:body" + ] + } + ] + } ], "help": [ "head", @@ -124,7 +137,7 @@ "box[Overview]:help×3", "box[Outbound]:help×6", "box[Inbound]:help×6", - "box[Server]:help×3", + "box[Server]:help×4", "box[Account]:help" ] } @@ -406,12 +419,14 @@ "columns": [ { "is-6": [ - "box[Log retention]:body" + "box[Log retention]:body", + "box[Sending rate limits]:body" ] }, { "is-6": [ - "box[Sending rate limits]:body" + "box[Notifications]:body", + "box[Notification mail]:record×2" ] } ] diff --git a/docs/assets/panel-redesign/panel/settings.html b/docs/assets/panel-redesign/panel/settings.html index ccee7fd..b81138e 100644 --- a/docs/assets/panel-redesign/panel/settings.html +++ b/docs/assets/panel-redesign/panel/settings.html @@ -87,9 +87,7 @@

    The inbound log also never holds more than 10 000 rows: refused mail is logged at the rate strangers knock on port 25.

    - -
    02

    Sending rate limits

    Read-only
    @@ -100,6 +98,43 @@
    + +
    +
    +
    03

    Notifications

    +
    +
    +

    From postmaster@mail.example.org, to every user who has an e-mail and has not turned them off under Account.

    +
    +
    + +
    +
    04

    Notification mail

    DNS records of the server's own name
    + +
    +

    DKIM

    publishedNot a secret · selector sp2026
    +
    +
    +
    +
    +
    +
    +
    +
    + +
    +

    SPF

    missingFor the server's own name, not for your domains
    +
    +
    +
    +
    +
    +
    +
    +

    Notifications are sent without it, and a receiver may file them as spam.

    +
    +
    +
    diff --git a/docs/assets/panel-redesign/panel/src/account.html b/docs/assets/panel-redesign/panel/src/account.html index 9cff4ff..e5ea912 100644 --- a/docs/assets/panel-redesign/panel/src/account.html +++ b/docs/assets/panel-redesign/panel/src/account.html @@ -16,6 +16,8 @@

    Your own address. A domain's report address can be filled with it from Domain settings.

    +
    +

    To this address, when something needs you: a DNS record of a domain stops matching, a rate limit refuses mail, the TLS certificate is about to expire, a message has waited in the queue for three days. What is sent and when

    diff --git a/docs/assets/panel-redesign/panel/src/health.html b/docs/assets/panel-redesign/panel/src/health.html index 57513c5..d9abcda 100644 --- a/docs/assets/panel-redesign/panel/src/health.html +++ b/docs/assets/panel-redesign/panel/src/health.html @@ -79,10 +79,29 @@ -
    -
    06

    Configuration

    Safe to run at any time
    -
    -

    Regenerates the OpenDKIM and Postfix configuration from the database and reloads both daemons. Use it after editing the files by hand, after restoring a backup, or when the running configuration looks out of step with the domain and application lists. It does not touch the queue or the TLS certificate.

    -
    +
    +
    +
    +
    06

    Notification mail

    warn
    +
    + + + + + +
    RecordState
    DKIM
    sp2026._domainkey.mail.example.org    		published
    SPF
    mail.example.org    		missing
    +
    +

    Sent from postmaster@mail.example.org. What to publish is under Settings.

    +
    +
    +
    +
    +
    +
    07

    Configuration

    Safe to run at any time
    +
    +

    Regenerates the OpenDKIM and Postfix configuration from the database and reloads both daemons. Use it after editing the files by hand, after restoring a backup, or when the running configuration looks out of step with the domain and application lists. It does not touch the queue or the TLS certificate.

    +
    +
    +
    diff --git a/docs/assets/panel-redesign/panel/src/help.html b/docs/assets/panel-redesign/panel/src/help.html index 64352f1..09df4e7 100644 --- a/docs/assets/panel-redesign/panel/src/help.html +++ b/docs/assets/panel-redesign/panel/src/help.html @@ -39,6 +39,7 @@
  • Backup and moving a domain
  • Users and roles
  • Settings
    • +
  • Notifications

    • Account

      @@ -75,11 +76,12 @@
      04

      Server

      Backup and moving a domain

      Full backup downloads one archive of the whole instance: data/ (the database, DKIM keys and application credentials), docker-compose.yml, .env and certs/. The Postfix queue is not in it. The backup is taken while the server is running, and Postfix keeps moving messages through the queue, so a copy could hold a message twice or miss it; mail still waiting for delivery is therefore not carried over, and a restored server starts with an empty queue. To keep the queue, stop the container and archive the project directory instead. The private key in certs/ has to be readable by the panel: give it to group 998 on the host (chgrp 998, chmod 640). Until then the panel refuses to make a backup and names the file, rather than hand over an archive without the key. It holds secrets, so leave Encrypt with a password ticked: the file is sealed as .spbk, the password is not stored, and without it nothing can be recovered. To restore, unpack it into an empty project directory (decrypt a .spbk first with selfpost-backup -decrypt) and start the same SelfPost version that made it; the panel refuses data from another version. The reverse-proxy configuration and mail.log are not included. One domain moves on its own: Export domain on its settings page writes a .json (or encrypted .spde) with its DKIM key and its applications' passwords, and Import a domain here reads it into another instance, so the published DNS needs no change.

      Users and roles

      The two roles are a reach, not a rank: every user is an administrator and signs in with a username and password. Global reaches the whole server — Overview, Server, the queue and every domain — and is the only role that adds or deletes domains and users. Domain reaches only the domains assigned to it, outbound and inbound separately (the same name on both lists is two assignments); All includes domains added later, and a domain user needs at least one domain or All on either list. The only global user cannot be demoted or deleted, and you cannot delete the account you are signed in with. A new password set here signs that user out of their other sessions.

      -

      Settings

      Settings holds what is true of the whole instance. Log retention is how many days the Outbound log keeps its rows, from 7 to 365 and 90 by default; a sweep every six hours deletes older ones, and it is the main driver of how fast /data grows. With the inbound relay on there is a second number, for the Inbound log, with the same range. It does not change the rotation of mail.log, which is daily with about two weeks kept. The sending rate limit shown under it is level 1, the per-client-IP ceiling set in .env: changing it needs a restart, and no level-2 limit can exceed it.

      +

      Settings

      Settings holds what is true of the whole instance. Log retention is how many days the Outbound log keeps its rows, from 7 to 365 and 90 by default; a sweep every six hours deletes older ones, and it is the main driver of how fast /data grows. With the inbound relay on there is a second number, for the Inbound log, with the same range. It does not change the rotation of mail.log, which is daily with about two weeks kept. The sending rate limit shown under it is level 1, the per-client-IP ceiling set in .env: changing it needs a restart, and no level-2 limit can exceed it. Notifications are turned on or off here for everyone.

      +

      Notifications

      The panel writes to its users when something needs them, from postmaster@ the server's hostname. Four things are reported. A sending domain's SPF, DKIM or DMARC record stops matching: sent once two hourly checks in a row have found it so, and once more when the record matches again. A level-2 rate limit refuses mail: sent at the first refusal, then at most once a day for the same limit. The TLS certificate is 14 days from expiry, and again at 3 days if it is still the same certificate. A message has waited in the queue for more than three days, with one more message when none is left. A global user is told all of it; a domain administrator is told about the DNS records and limits of their own domains.

      Each user turns notifications on or off under Account and needs an e-mail there; Server › Settings turns them off for everyone. They are the panel's own mail: not rows of the Outbound log, and not counted against any limit.

      For that mail to arrive, the server's own name needs two DNS records of its own, as each of your domains does: a DKIM key, which the panel generates and signs notifications with, and an SPF record, v=spf1 a -all. Server › Settings gives both with the values to publish, and Server › Health shows whether they are in place. Without them notifications are still sent, and a receiver may file them as spam. Mail of your domains does not depend on either.

    05

    Account

    -

    Your account

    Account is your own, whatever your role: your username and e-mail, and your password. Changing the password signs out every other session of this account and keeps the one you are using; applications have their own logins and are not affected.

    +

    Your account

    Account is your own, whatever your role: your username and e-mail, whether the panel sends you notifications, and your password. Changing the password signs out every other session of this account and keeps the one you are using; applications have their own logins and are not affected.

    diff --git a/docs/assets/panel-redesign/panel/src/settings.html b/docs/assets/panel-redesign/panel/src/settings.html index 6dd622c..1242104 100644 --- a/docs/assets/panel-redesign/panel/src/settings.html +++ b/docs/assets/panel-redesign/panel/src/settings.html @@ -21,9 +21,7 @@

    The inbound log also never holds more than 10 000 rows: refused mail is logged at the rate strangers knock on port 25.

    - -
    02

    Sending rate limits

    Read-only
    @@ -34,6 +32,43 @@
    + +
    +
    +
    03

    Notifications

    +
    +
    +

    From postmaster@mail.example.org, to every user who has an e-mail and has not turned them off under Account.

    +
    +
    + +
    +
    04

    Notification mail

    DNS records of the server's own name
    + +
    +

    DKIM

    publishedNot a secret · selector sp2026
    +
    +
    +
    +
    +
    +
    +
    +
    + +
    +

    SPF

    missingFor the server's own name, not for your domains
    +
    +
    +
    +
    +
    +
    +
    +

    Notifications are sent without it, and a receiver may file them as spam.

    +
    +
    +
    diff --git a/docs/plans/panel-notifications.md b/docs/plans/panel-notifications.md index fb1bc18..8a20ec6 100644 --- a/docs/plans/panel-notifications.md +++ b/docs/plans/panel-notifications.md @@ -40,10 +40,23 @@ From `postmaster@`, submitted locally. Not from one of the sending domains (owner): with several domains the choice is arbitrary, and a message about the certificate has no business coming from a domain. -The server's name usually has no DKIM key. One DNS record is enough for such -mail to pass SPF and DMARC on the name itself: `v=spf1 a -all` for the -hostname. Server › Health gains that check next to reverse DNS, and the guide -describes it. Without the record notifications are still sent. +These messages have to arrive (owner: "we need the best deliverability for +them"), so the server's own name gets what a sending domain has: + +- a **DKIM key for the hostname**, generated by the panel, with which + notifications are signed - no domain has to be chosen for it. An SPF record + alone would pass DMARC, but not after the user's mailbox forwards the + message on, and large receivers treat unsigned mail more strictly; +- an **SPF record** for the hostname, `v=spf1 a -all`. + +The records themselves are under **Server › Settings** (owner: "the DNS +records go to Settings, Health has only the status"), in a box of their own +drawn with the record component of a domain's DNS page: host, value to +publish, copy buttons, state. **Server › Health** has a card of its own, +*Notification mail*, with the state of each record and a link to Settings. +A DMARC record for the hostname is not asked for: the name inherits its +parent domain's policy, and with SPF and DKIM aligned it passes any. +Without the records notifications are still sent, and the card warns. Notifications are the panel's own mail: they are not rows of the Outbound log and count against no level-2 limit. @@ -94,7 +107,7 @@ to the owner before any code ([panel-redesign.md](panel-redesign.md) ## Implementation checklist -- [ ] Mockups: Account checkbox, Settings switch, Health SPF check, help topic; accepted by the owner (`design:` commit) +- [x] Mockups: Account checkbox, Settings switch and records, Health status card, help topic; accepted by the owner 2026-10-12 (`design:` commit) - [ ] Migration and store: user flag, instance switch, event state - [ ] Sending: local submission from `postmaster@`, message text - [ ] Background checker: DNS, certificate, queue; the rules of *When a message is sent* diff --git a/docs/roadmap.md b/docs/roadmap.md index 70bde3a..a813878 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -35,7 +35,7 @@ in `git log` and [CHANGELOG.md](../CHANGELOG.md). | template-data-typing | Typed structs for template data instead of `map[string]any` | candidate | — | — | | structured-logging | `log/slog` with levels and fields | candidate | — | — | | review-2026-08-followups | Remaining findings of the 2026-08-19 code review | candidate | — | — | -| panel-notifications | E-mail notifications about important events | agreed | 0/10 | [plans/panel-notifications.md](plans/panel-notifications.md) | +| panel-notifications | E-mail notifications about important events | in progress | 1/10 | [plans/panel-notifications.md](plans/panel-notifications.md) | | delivery-log-storage | Keep a message's `mail.log` lines with its send-log row | shipped `2.2.0` | 8/8 | [plans/delivery-log-storage.md](plans/delivery-log-storage.md) | | password-reset | Password reset by e-mail | candidate | — | — | | phone-desktop-mode | A phone browser in "desktop site" mode gets the phone navigation | candidate | — | — |