ci: drop per-arch GHCR tags via GitHub Packages API

imagetools has no rm subcommand; the merge cleanup had been failing silently. Document Gitea-to-GitHub tag mirror pitfalls in development.md. CHANGELOG [1.3.0] updated. Co-Authored-By: Cursor <cursoragent@cursor.com>
release: 1.3.0
2026-08-15 22:57:34 +03:00 · 2026-08-14 21:51:29 +03:00 · 2026-08-14 21:47:09 +03:00 · 2026-08-14 21:44:33 +03:00 · 2026-08-14 19:48:20 +03:00 · 2026-08-14 19:43:06 +03:00
9 changed files with 791 additions and 499 deletions
@@ -1,13 +1,9 @@
 name: release
 # Publishes an immutable, version-tagged image on ghcr.io (spec 10.1).
-# Ordinary commits do not publish anything. A pushed tag matching vX.Y.Z does,
+# Ordinary commits and bare git tag pushes do not publish anything. A published
-# and so does workflow_dispatch when it supplies a SemVer X.Y.Z version (or
+# GitHub Release runs this workflow directly (same pattern as gosentry / imap-scrub).
-# runs on such a tag). A dispatch from main without that input must fail in
+# You can also run it manually via workflow_dispatch with an explicit SemVer X.Y.Z.
 # prepare — it must not publish ghcr.io/...:main. The version is the single
 # source that goes into both the image tag and the panel binary's -ldflags
 # version, so the two can never drift apart (the invariant restore's version
 # check in spec 7.5.A depends on).
 #
 # Native per-architecture builds (see docs/development.md), not qemu:
 # running the full Postfix/OpenDKIM stack under emulation for the e2e gate
@@ -15,18 +11,17 @@ name: release
 # tag on its own native runner; a merge job then combines them into the one
 # manifest tag documented in deploy/docker-compose.yml. "test, then push" (not
 # push-by-digest then test) is deliberate: it means the bytes that get tagged
-# are exactly the bytes that passed e2e, at the cost of per-arch tags lingering
+# are exactly the bytes that passed e2e. Per-arch tags are pushed only so
-# in the registry as a side effect (harmless — the version tag's immutability,
+# imagetools can assemble the multi-arch manifest; merge removes them from GHCR
-# spec 10.1, is about that tag, not these).
+# so operators see a single version tag (spec 10.1).
 on:
-  push:
+  release:
-    tags:
+    types: [published]
      - "v[0-9]+.[0-9]+.[0-9]+"
  workflow_dispatch:
    inputs:
      version:
-        description: "Image version as X.Y.Z (no v prefix). Required unless this run is already on a vX.Y.Z tag."
+        description: "Image version as X.Y.Z (no v prefix)."
-        required: false
+        required: true
        type: string
 permissions:
@@ -43,15 +38,18 @@ jobs:
        id: version
        env:
          INPUT_VERSION: ${{ github.event.inputs.version }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}
          EVENT_NAME: ${{ github.event_name }}
        run: |
          set -euo pipefail
          if [ "$EVENT_NAME" = "release" ]; then
            raw="${RELEASE_TAG:-}"
          else
            raw="${INPUT_VERSION:-}"
          if [ -z "$raw" ] && [[ "${GITHUB_REF_NAME}" == v[0-9]*.[0-9]*.[0-9]* ]]; then
            raw="${GITHUB_REF_NAME#v}"
          fi
          raw="${raw#v}"
          if ! [[ "$raw" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "::error::release version is not SemVer X.Y.Z (ref is ${GITHUB_REF_NAME}; pass inputs.version on workflow_dispatch). Refusing to publish ghcr.io/${{ github.repository }}:${GITHUB_REF_NAME}"
+            echo "::error::release version is not SemVer X.Y.Z (event=${EVENT_NAME}; tag=${RELEASE_TAG:-} input=${INPUT_VERSION:-}). Refusing to publish ghcr.io/${{ github.repository }}:${raw:-?}"
            exit 1
          fi
          echo "version=${raw}" >> "$GITHUB_OUTPUT"
@@ -69,6 +67,8 @@ jobs:
    runs-on: ${{ matrix.runner }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: v${{ needs.prepare.outputs.version }}
      - uses: docker/setup-buildx-action@v3
@@ -133,6 +133,10 @@ jobs:
    needs: [prepare, build]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: v${{ needs.prepare.outputs.version }}
      - uses: docker/setup-buildx-action@v3
      - name: Log in to ghcr.io
@@ -172,3 +176,29 @@ jobs:
            attempt=$((attempt + 1))
            backoff=$((backoff * 2))
          done
      - name: Remove per-arch tags from GHCR
        # Side-effect tags for imagetools assembly only — not part of the public
        # version surface (deploy/docker-compose.yml pins X.Y.Z, not X.Y.Z-amd64).
        # imagetools has no "rm" subcommand; delete via the GitHub Packages API.
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          version="${{ needs.prepare.outputs.version }}"
          owner="${{ github.repository_owner }}"
          pkg="${{ github.event.repository.name }}"
          api="/users/${owner}/packages/container/${pkg}/versions"
          for suffix in amd64 arm64; do
            tag="${version}-${suffix}"
            mapfile -t ids < <(gh api "$api" --paginate \
              --jq ".[] | select([.metadata.container.tags[]] | index(\"${tag}\")) | .id")
            if [ "${#ids[@]}" -eq 0 ]; then
              echo "no GHCR package version for tag ${tag}"
              continue
            fi
            for id in "${ids[@]}"; do
              echo "deleting GHCR package version ${id} (tag ${tag})"
              gh api -X DELETE "${api}/${id}"
            done
          done
@@ -5,6 +5,13 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version
 ## [Unreleased]
 ## [1.3.0] - 2026-08-14
 Security and quality after 1.2.5: domain-admin send-log authorization,
 fail-closed sign-in and application delete, level-2 rate-limit race fix,
 restore Resync, expanded tests, operator docs, release CI, and OFL for IBM
 Plex. Upgrading from 1.2.x is a tag bump; no migration.
 ### Added
 - licence: the SIL Open Font License 1.1 text now travels with the IBM Plex
@@ -74,24 +81,78 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version
  through a confirmation page, the same pattern as domain deletion, instead of
  a plain submit button next to Save with no confirmation at all.
 - panel (restore): after a backup is extracted and the version guard passes,
  the panel runs one mail-path Resync on the first boot — OpenDKIM's tables
  and Postfix's sender map are re-derived from SQLite and the daemons are
  reloaded, so drift between the archive and the database is healed before
  mail flows. Later starts skip that step; the Status page Reload button runs
  the same Resync on demand. The `internal/backup` package comment now matches
  this behaviour.
 - ci (GHCR): per-arch package tags (`X.Y.Z-amd64`, `X.Y.Z-arm64`) are dropped
  after the manifest merge via the GitHub Packages API. The merge job had called
  `docker buildx imagetools rm`, which is not a valid subcommand — cleanup failed
  with a warning and the side-effect tags stayed in the registry.
 ### Changed
 - docs: operator and as-built docs aligned with the code after a full
  pass — [architecture.md](docs/architecture.md) route table now marks
  **global** routes (404 for domain administrators) and documents the
  one-time restore Resync in Persistence; session/password and restore-session
  wording corrected in [guide.md](docs/guide.md) and architecture (own-password
  change vs admin reset, no "logout everywhere", immediate session restore on
  the next request, PTR cache ≈1 min, decrypt has no version check, restore
  Resync on first boot, domain add/delete/import and `POST /reload` global-only,
  Settings DMARC global-only); [README.md](README.md) port-587 and quick-start
  volume wording fixed; [security.md](docs/security.md) CSRF ADR points at
  `authz.go` for route gating. No behaviour change.
 - docs: [guide.md](docs/guide.md) reorganised into **Installation**, **Instance
  administration**, and **Domain administration** — DNS setup, operations,
  rate limiting, and backup sections follow the instance/domain boundary
  instead of mixing them. **Installation** now reads Ports → Local trial →
  Initial setup → Full deployment (with the fixed image tag nested under it) →
  Environment variables → Reverse proxy; the step-by-step production deploy and
  per-proxy TLS commands move here from README's "Reference deploy" (README
  keeps a short pointer). Internal (non-operator) environment variables move
  to [architecture.md](docs/architecture.md) § Configuration; the guide keeps
  a one-line pointer. **Full backup and restore** gains worked commands for
  in-place restore, move-to-a-new-host, and encrypted-backup decrypt-first,
  plus the version-mismatch error text. README anchors updated for the new
  headings. No behaviour change.
 - docs: the 2026-08-13 full-tree review plan is complete — every phase (P0–P7)
  is closed — and `docs/plans/code-review.md` is deleted per its own exit
-  criteria (history in git and in this file). The
+  criteria (history in git and in this file). The plan covered architecture,
-  [roadmap](docs/roadmap.md)'s recommended order returns to **queue-retries**
+  quality, GUI, tests, and licence work; P0 was domain-admin send-log
-  and then **inbound-relay**.
+  authorization. The [roadmap](docs/roadmap.md)'s recommended order returns to
  **queue-retries** and then **inbound-relay**; it still records
  **schema-squash** (replace the 1.x SQLite migration chain with a 2.x baseline;
  not a reason to cut a major on its own).
 - licence: [NOTICE](NOTICE) tells modifiers to update `SourceURL` in
  `internal/legal/legal.go` (the value the panel footer actually injects), not
-  `layout.html`. `release.yml` refuses a `workflow_dispatch` whose version is
+  `layout.html`. Per-file `SPDX-License-Identifier` headers on the two command
-  not SemVer `X.Y.Z`, so a run from `main` cannot publish `ghcr.io/...:main`.
+  packages were dropped so the tree is consistent; AGPL-3.0 does not require
-  Per-file `SPDX-License-Identifier` headers on the two command packages were
+  them ([development.md](docs/development.md) § External libraries). Deleted the
  dropped so the tree is consistent; AGPL-3.0 does not require them
  ([development.md](docs/development.md) § External libraries). Deleted the
  completed `docs/plans/logrotate-mode.md` (history in git and
  [1.2.3](#123---2026-08-12)).
 - ci: the release image is published only for a **published** GitHub Release
  (`vX.Y.Z`) or a manual `workflow_dispatch` with an explicit SemVer version — a
  bare git tag push no longer starts the build. `release.yml` listens for
  `release: published`, checks out that tag (not `main` HEAD), e2e-gates each
  native arch build, merges `X.Y.Z-amd64` and `X.Y.Z-arm64` into one manifest,
  then removes the per-arch tags from GHCR via the GitHub Packages API so
  operators see only `ghcr.io/mixeme/selfpost:X.Y.Z` (what
  `deploy/docker-compose.yml` pins). A dispatch whose version input is missing
  or not `X.Y.Z` fails in `prepare`. [development.md](docs/development.md)
  documents draft vs published releases, why deleting a release tag converts
  it back to draft, and Gitea → GitHub tag-mirror pitfalls (do not prune release
  tags on GitHub; a mirrored `v1.0.0` still runs that tag's `on: push: tags`
  workflow).
 - test: the authorization and sign-in surfaces that had no tests now have them.
  The login limiter is covered for its ceiling, its per-address scope, the reset
  at the end of a window and the sweep that keeps finished buckets out of
@@ -108,13 +169,15 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version
  downloaded from a running panel through `POST /backup` (plain and encrypted),
  unpacked the way `tar -xzf` unpacks it onto the `/data` bind mount, and a
  second panel is booted on the result through the startup order the panel
-  itself uses — version guard, database, services, HTTP application. The
+  itself uses — version guard, database, one Resync when restoring, then
-  restored panel shows the domain and journal the archive carried, finds the
+  services and the HTTP application. The restored panel shows the domain and
-  DKIM key, SASL database and Postfix sender map where its configuration says
+  journal the archive carried, finds the DKIM key, SASL database and Postfix
-  they are, does not reopen the one-time setup link, and still honours a
+  sender map where its configuration says they are, does not reopen the
-  session that predates the backup. A data directory left by another version is
+  one-time setup link, and still honours a session that predates the backup.
-  refused with both versions named and the manifest kept. `serveHTTP` is split
+  Drifted on-disk maps are healed by that Resync step
-  in two so that composition can be started without binding a port; no
+  (`TestResyncAfterRestoreHealsDriftedMaps`). A data directory left by another
  version is refused with both versions named and the manifest kept. `serveHTTP`
  is split in two so that composition can be started without binding a port; no
  behaviour change.
 - test (e2e): the CoreDNS image is pinned to `1.14.6` instead of `latest`, so
@@ -144,13 +207,6 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version
  prompts existed — and why that is acceptable (the prompt is a mis-click
  guard, not an authorization boundary).
 - docs: full-tree review plan (`docs/plans/code-review.md`, since completed
  and deleted — history in git)
  — architecture, quality, GUI, tests, licence; P0 is domain-admin send-log
  authorization. Roadmap queues that plan ahead of inbound-relay and records
  `schema-squash` (replace the 1.x SQLite migration chain with a 2.x baseline;
  not a reason to cut a major on its own).
 - docs: security and operator docs updated for the panel that has shipped
  global administrators and domain-admins since 1.2.0. The CSRF ADR in
  [security.md](docs/security.md) no longer argues from "single-user"; it now
@@ -158,15 +214,12 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version
  check defends against, and gives a new revisit trigger. Dropped the
  unimplemented "or argon2" alternative for the password hash.
  [guide.md](docs/guide.md) documents the Users page and the two roles,
-  the Settings page's default DMARC report address, level-2 rate limiting's
+  level-2 rate limiting's fail-open behaviour, and that a domain-admin can
-  fail-open behaviour, that restoring an older backup can resurrect sessions,
+  export working SASL passwords for domains assigned to them.
-  and that a domain-admin can export working SASL passwords for domains
+  [architecture.md](docs/architecture.md) gains `/license` and the
-  assigned to them. [architecture.md](docs/architecture.md)'s route table now
+  `/account` → `/settings` redirect in the route table (later expanded for
-  lists `/license` and the `/account` → `/settings` redirect. Fixed the
+  RBAC in the doc-alignment pass above). Corrected stale
-  `internal/backup` package comment, which claimed the panel regenerates
+  `admin.dmarc_report_email` references in
  Postfix/OpenDKIM state from SQLite on every restore boot (it only runs the
  version guard; drifted daemon state is healed by the Status page's Reload
  button). Corrected stale `admin.dmarc_report_email` references in
  [roadmap.md](docs/roadmap.md) and
  [docs/plans/dmarc-reports.md](docs/plans/dmarc-reports.md) to the setting's
  actual home after migration `0005`. No behaviour change.
@@ -181,13 +234,6 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version
  longer promises in-panel report reception in a future release — SelfPost
  does not receive inbound mail.
 - panel (restore): after a backup is extracted and the version guard passes,
  the panel runs one mail-path Resync on the first boot — OpenDKIM's tables
  and Postfix's sender map are re-derived from SQLite and the daemons are
  reloaded, so drift between the archive and the database is healed before
  mail flows. Later starts skip that step; the Status page Reload button runs
  the same Resync on demand.
 ## [1.2.5] - 2026-08-13
 Rate-limit form polish after 1.2.4. Upgrading is a tag bump; no migration.
@@ -26,7 +26,7 @@ send log and DNS checks in the panel, encrypted backups.
 - DNS status checks (PTR, SPF, DKIM, DMARC) with in-panel re-check
 - Two-level rate limiting — IP backstop (Postfix), per-domain ceilings, and trusted-IP app overrides
 - Full-server backup and single-domain export/import (optional password encryption)
- Single Docker image; data in a `./data` bind mount
+- Single Docker image; production data in a `./data` bind mount (the quick start below uses a named Docker volume instead)
 ## Documentation
@@ -76,14 +76,15 @@ For every domain you add in the panel:
 - [ ] DKIM TXT record (value shown on the domain page)
 - [ ] DMARC `_dmarc` TXT record
-See [DNS setup](docs/guide.md#dns-setup) in the operator guide.
+See [Domain-level DNS](docs/guide.md#domain-level-dns-spf-dkim-dmarc) in the operator guide.
 ## Quick start
 > **First boot — create the admin account.** On a fresh container SelfPost prints
 > a **one-time setup URL** (valid ten minutes). Open it in a browser to choose
 > the administrator username and password. Until you do, the panel has no login.
-> Production deploy: [step 3](#3-start-selfpost).
+> Production deploy: [Full deployment](docs/guide.md#full-deployment) in the
 > operator guide.
 One container, panel at `http://127.0.0.1:8080` — no reverse proxy, no TLS
 files, no compose files. Good for clicking through the UI on your machine;
@@ -95,7 +96,7 @@ docker run --rm -d --name selfpost-try \
  -e SELFPOST_HOSTNAME=mail.local.test \
  -e PANEL_COOKIE_SECURE=false \
  -v selfpost-try-data:/data \
-  ghcr.io/mixeme/selfpost:1.2.5
+  ghcr.io/mixeme/selfpost:1.3.0
 ```
 **Get the setup URL** (pick one):
@@ -129,136 +130,17 @@ TLS PEM files at `./certs` (read by Postfix on 465/587). The panel is reached
 only through a reverse proxy on 443 — port 8080 is bound to localhost in the
 default compose file.
-| Artefact | Path |
+Full walkthrough — fetching the base files, setting up a reverse proxy and
-|---|---|
+TLS (Apache/nginx/Caddy/Traefik), starting the container, and wiring up
-| Compose file (fixed image tag) | [deploy/docker-compose.yml](deploy/docker-compose.yml) |
+DNS — lives in the operator guide's [Full
-| Environment template | [deploy/.env.example](deploy/.env.example) |
+deployment](docs/guide.md#full-deployment) section, with proxy-specific
-| Apache vhost (recommended) | [deploy/apache/selfpost-vhost.conf](deploy/apache/selfpost-vhost.conf) |
+commands under [Reverse proxy](docs/guide.md#reverse-proxy-mandatory).
 | nginx | [deploy/nginx/](deploy/nginx/) |
 | Caddy | [deploy/caddy/](deploy/caddy/) |
 | Traefik | [deploy/traefik/](deploy/traefik/) |
-### 1. Fetch the base files
+The compose file always publishes **465** and **587**; Postfix listens on 587
-
+only when `SUBMISSION_ENABLE=true` (see [Ports](docs/guide.md#ports)). Bump the
-```sh
+pinned image tag deliberately when upgrading, never `:latest` ([why](docs/guide.md#fixed-image-tag)). Optional
-mkdir -p selfpost/data selfpost/certs && cd selfpost
+variables (`TRUSTED_PROXY_CIDR`, rate limits, retention): see [Environment
-curl -O https://raw.githubusercontent.com/mixeme/selfpost/main/deploy/docker-compose.yml
+variables](docs/guide.md#environment-variables).
 curl -O https://raw.githubusercontent.com/mixeme/selfpost/main/deploy/.env.example
 cp .env.example .env
 ```
 Edit `.env` — at minimum set `SELFPOST_HOSTNAME` to your mail hostname (bare
 FQDN, e.g. `mail.example.com`). It must match the PTR record you request from
 your provider and the certificate your proxy will obtain.
 ### 2. Reverse proxy and TLS
 Pick one proxy. In every case the proxy terminates HTTPS for the panel; the
 same certificate must end up under `./certs` as `fullchain.pem` and
 `privkey.pem` so Postfix can serve it on 465 (and 587 if enabled). The proxy
 must **pass the original `Host` header** — details and rationale:
 [Reverse proxy](docs/guide.md#reverse-proxy-mandatory).
 **Apache (recommended, on the host).** Install Apache with `ssl`, `proxy`, and
 `proxy_http` enabled. Copy
 [deploy/apache/selfpost-vhost.conf](deploy/apache/selfpost-vhost.conf) into your
 vhost directory, replace `mail.example.com` with your hostname, enable the site,
 then issue a certificate:
 ```sh
 sudo certbot --apache -d mail.example.com
 ```
 Point `./certs` at the PEM files certbot wrote (symlink is fine):
 ```sh
 ln -s /etc/letsencrypt/live/mail.example.com certs
 ```
 **nginx (containerised).** From the `deploy/` directory, merge the nginx
 fragment and issue the first certificate before nginx can serve HTTPS:
 ```sh
 docker compose -f docker-compose.yml -f nginx/docker-compose.nginx.yml \
  run --rm certbot certonly --webroot -w /var/www/certbot \
  -d mail.example.com --email you@example.com --agree-tos --no-eff-email
 docker compose -f docker-compose.yml -f nginx/docker-compose.nginx.yml up -d
 ```
 Edit [deploy/nginx/nginx.conf.example](deploy/nginx/nginx.conf.example) and
 replace `mail.example.com` first. The fragment bind-mounts certbot's output into
 both nginx and SelfPost.
 **Caddy (containerised, automatic ACME).** Edit
 [deploy/caddy/Caddyfile](deploy/caddy/Caddyfile) and the `<hostname>` placeholders
 in [deploy/caddy/docker-compose.caddy.yml](deploy/caddy/docker-compose.caddy.yml),
 then:
 ```sh
 docker compose -f docker-compose.yml -f caddy/docker-compose.caddy.yml up -d
 ```
 Verify Caddy's on-disk cert path for your version before relying on the
 default mount — see the comment at the top of the Caddy compose fragment.
 **Traefik (containerised).** Edit the `Host(...)` label and ACME email in
 [deploy/traefik/docker-compose.traefik.yml](deploy/traefik/docker-compose.traefik.yml),
 start the stack, then extract PEM files for Postfix whenever Traefik issues or
 renews a certificate:
 ```sh
 docker compose -f docker-compose.yml -f traefik/docker-compose.traefik.yml up -d
 ./traefik/extract-cert.sh ./traefik/letsencrypt/acme.json mail.example.com ./traefik/extracted-certs
 ```
 Schedule `extract-cert.sh` (cron or a timer) alongside Traefik's renewals.
 ### 3. Start SelfPost
 If you used Apache on the host (step 2, first option), start only the base
 compose file from your `selfpost/` directory:
 ```sh
 docker compose up -d
 ```
 The nginx/Caddy/Traefik fragments from step 2 already include `docker compose up
 -d` — skip this if you ran one of those.
 **Get the setup URL** — open it in a browser to create the admin account
 ([first boot](#quick-start)):
 ```sh
 docker compose logs selfpost 2>&1 | grep -m1 'http'
 ```
 ```sh
 cat ./data/setup-token
 ```
 The file is deleted as soon as setup completes. If logs are shipped to a
 central aggregator, prefer `cat ./data/setup-token` so the bearer token does
 not enter the log pipeline.
 ### 4. DNS and sending
 Before sending real mail:
 1. Confirm PTR/rDNS for the server IP points at `SELFPOST_HOSTNAME` (Status
   page → *Re-check*).
 2. For each domain you add in the panel, publish SPF, DKIM, and DMARC at the
   same time ([DNS setup](docs/guide.md#dns-setup)).
 3. Warm up a new IP gradually ([IP warmup](docs/guide.md#ip-warmup)).
 ### Ports and upgrades
 The compose file maps **465** (always) and **587** (when
 `SUBMISSION_ENABLE=true`). Bump the pinned image tag deliberately when
 upgrading — never use `:latest` ([why](docs/guide.md#fixed-image-tag)).
 Optional variables (`TRUSTED_PROXY_CIDR`, rate limits, retention): see
 [Environment variables](docs/guide.md#environment-variables).
 ## License
@@ -17,7 +17,7 @@ var documentedPublic = []string{
 	"TRUSTED_PROXY_CIDR",
 }
-// documentedInternal matches guide.md "Internal variables (not part of the operator interface)".
+// documentedInternal matches architecture.md § Configuration "Internal env vars".
 var documentedInternal = []string{
 	"SELFPOST_DATA_DIR",
 	"SELFPOST_DB_PATH",
@@ -22,7 +22,7 @@
 services:
  selfpost:
-    image: ghcr.io/mixeme/selfpost:1.2.5
+    image: ghcr.io/mixeme/selfpost:1.3.0
    restart: unless-stopped
    environment:
      SELFPOST_HOSTNAME: "${SELFPOST_HOSTNAME:?set the mail/panel hostname, e.g. mail.example.com}"
@@ -154,7 +154,10 @@ state for an older message and the page reports it as such, not as a failure.
 ## Panel HTTP surface
 Canonical routes: [internal/web/web.go](../internal/web/web.go). Authenticated
-unless noted. The table below is a summary — HTMX fragment endpoints
+unless noted. Routes marked **global** return **404** for domain administrators
 (`requireGlobal()` in
 [internal/web/handlers/authz.go](../internal/web/handlers/authz.go)). The table
 below is a summary — HTMX fragment endpoints
 (`/status/fragment`, `/deliveries/rows`, `/mail-queue/body`,
 `/system-log/body`, …) and every POST variant live in `web.go`.
@@ -165,17 +168,17 @@ unless noted. The table below is a summary — HTMX fragment endpoints
 | `/setup/*` | One-time admin bootstrap |
 | `/login`, `/logout` | Session auth |
 | `/account` | 308 redirect to `/settings` (pre-1.2.3 route, kept as a compat shim) |
-| `/status` | Process, cert, socket, PTR checks; machine CPU/memory/network |
+| `/status`, `/status/*` | **Global.** Process, cert, socket, PTR checks; machine CPU/memory/network |
-| `/domains`, `/domains/*` | Domain and application CRUD, DKIM, L2 limits |
+| `/domains` | Domain list; `POST /domains` (add domain) is **global** |
-| `/domains/import` | Domain import (`POST`; form on the Backup page) |
+| `/domains/{id}`, `/domains/{id}/*` | Assigned-domain detail for domain-admins; delete domain is **global** |
-| `/deliveries` | Send log with filters |
+| `/domains/import` | **Global.** Domain import (`POST`; form on the Backup page) |
-| `/deliveries/{id}` | One send-log row in full, with its `mail.log` lines |
+| `/deliveries`, `/deliveries/{id}` | Send log with filters; scoped to assigned domains for domain-admins |
-| `/mail-queue` | Postfix queue view |
+| `/mail-queue`, `/mail-queue/*` | **Global.** Postfix queue view |
-| `/system-log` | `mail.log` tail |
+| `/system-log`, `/system-log/*` | **Global.** `mail.log` tail |
-| `/reload` | Reload OpenDKIM + Postfix maps |
+| `/reload` | **Global.** `POST` — reload OpenDKIM + Postfix maps |
-| `/backup` | Full backup download (page also hosts the import form) |
+| `/backup`, `/backup/*` | **Global.** Full backup download (page also hosts the import form) |
-| `/settings` | Admin username/password and DMARC report address |
+| `/settings` | Username/password for any user; DMARC report default is **global** only |
-| `/users`, `/users/*` | Panel user CRUD (global admin only) |
+| `/users`, `/users/*` | **Global.** Panel user CRUD |
 HTMX polling refreshes monitoring fragments (5 s while the operator is active on
 the page, 30 s when the tab is visible but idle, none when hidden — scheduled in
@@ -194,13 +197,16 @@ holds the cookie works after process restart, redeploy, or full backup restore.
  absolute cap (regular use keeps the session alive indefinitely).
 - **Renewal** — DB `last_seen` and cookie `Max-Age` update at most once per hour
  (`renewThreshold` in [internal/web/auth/session.go](../internal/web/auth/session.go)).
- **Password change** — all other sessions are deleted; the current session stays
+- **Password change on `/settings`** — changing your own password deletes
-  active ([internal/store/sessions.go](../internal/store/sessions.go),
+  every other session for that user; the current session stays active
  ([internal/store/sessions.go](../internal/store/sessions.go),
  [handlers_settings.go](../internal/web/handlers/handlers_settings.go)).
  A global administrator resetting another user's password on `/users` updates
  the hash but does not delete that user's existing sessions.
-Restoring an **older** backup also restores session rows: a session invalidated
+Restoring an **older** backup also restores session rows: a session removed
-after that backup was taken can become valid again if the browser still has the
+after that backup was taken can become valid again if the browser still holds
-cookie and idle timeout has not expired.
+the cookie and the restored row's `expires_at` has not passed.
 ---
@@ -295,9 +301,13 @@ Not in `/data`: TLS certificates (reverse-proxy mount), Postfix queue
 `mail.log` via logrotate (14 rotated files, check every 6h, rename +
 `postfix reload` in `postrotate` — see § Log tailer above).
-**Backup:** panel button or `selfpost-backup` CLI — SQLite snapshot + tar of
+**Restore:** panel button or `selfpost-backup` CLI — SQLite snapshot + tar of
 `/data` tree, minus `log/`, the setup token and any `tls/`; version check on
-restore. Stopped-container `tar` of `./data` is safe (see guide).
+restore. On the first successful boot after restore, the panel runs one
 **Resync** — OpenDKIM's tables and Postfix's sender map are re-derived from
 SQLite and both daemons are reloaded, so drift between the extracted archive
 and the database is healed before mail flows (same step as `POST /reload` on
 demand). Stopped-container `tar` of `./data` is safe (see guide).
 **Optional encryption** of the two secret-bearing downloads
 ([internal/secretfile](../internal/secretfile/secretfile.go)): password →
@@ -319,5 +329,33 @@ origin check, no CSRF tokens) are documented there separately.
 ## Configuration
-Public and internal env vars: [guide § Environment variables](guide.md#environment-variables).
+Public env vars: [guide § Environment variables](guide.md#environment-variables).
 Regression test: [cmd/panel/envdoc_test.go](../cmd/panel/envdoc_test.go).
 **Internal env vars.** The following are read by the panel or startup scripts
 but are not part of the operator interface — not meant to be changed in a
 normal deployment; documented here so an accidental override reads as
 unsupported rather than as a missing doc:
 - **Panel paths and tuning:** `SELFPOST_DATA_DIR` (`/data`), `SELFPOST_DB_PATH`
  (`/data/selfpost.db`), `SELFPOST_SETUP_TOKEN_FILE`
  (`/data/setup-token`), `PANEL_HTTP_ADDR` (`:8080`),
  `JOURNAL_MILTER_SOCKET` (`/run/selfpost/journal.sock`), `MAIL_LOG`
  (`/data/log/mail.log` — read by the panel and written by Postfix, so a change
  here has to be matched in `build/postfix-config.sh`),
  `PANEL_COOKIE_SECURE` (`true`), `OPENDKIM_SOCKET`
  (`/run/opendkim/opendkim.sock`), `OPENDKIM_DIR` (`/data/opendkim`),
  `DKIM_SELECTOR_DEFAULT` (`selfpost`), `SASL_DB_PATH`
  (`/data/sasl/sasldb2`), `SASL_REALM` (defaults to `SELFPOST_HOSTNAME`),
  `POSTFIX_DIR` (`/data/postfix`), `POSTFIX_SENDER_LOGIN_MAPS`
  (`/data/postfix/sender_login_maps` — read by Postfix config only; the panel
  always writes `<POSTFIX_DIR>/sender_login_maps`, so overriding this env alone
  desyncs the map Postfix reads from the file the panel maintains).
 - **Milter and Postfix startup:** `MILTER_CONNECT_TIMEOUT` (`15s`),
  `MILTER_COMMAND_TIMEOUT` (`15s`), `MILTER_CONTENT_TIMEOUT` (`30s`),
  `MILTER_WAIT_TIMEOUT` (`30` seconds).
 - **Background maintenance:** `TLS_RELOAD_INTERVAL_SECONDS` (`86400` — daily
  `postfix reload` to pick up renewed certificates),
  `LOGROTATE_INTERVAL_SECONDS` (`21600` — check `mail.log` rotation every six
  hours; logrotate keeps 14 rotated files on a daily schedule, and each
  rotation triggers `postfix reload`).
@@ -191,11 +191,12 @@ tag / push only on explicit request (see `release.yml`).
 ### Release image
-The release image is published **only** for a SemVer version `X.Y.Z`: a pushed
+The release image is published **only** for a SemVer version `X.Y.Z`: a
-tag `vX.Y.Z`, or a `workflow_dispatch` that supplies that version (or runs on
+**published** GitHub Release whose tag is `vX.Y.Z`, or a `workflow_dispatch`
-such a tag). Ordinary commits, and a dispatch from `main` without a version
+that supplies that version. Pushing a git tag alone does not publish. Ordinary
-input, do not publish. The version is the single source that drives the image
+commits, and a dispatch from `main` without a version input, do not publish.
-tag and `-ldflags` in the binaries so they cannot drift apart.
+The version is the single source that drives the image tag and `-ldflags` in
 the binaries so they cannot drift apart.
 **Steps (on explicit request):**
@@ -203,8 +204,42 @@ tag and `-ldflags` in the binaries so they cannot drift apart.
   tag in [deploy/docker-compose.yml](../deploy/docker-compose.yml) (and any
   local-trial image references) in the **same** release commit.
 2. Create and push git tag `vX.Y.Z` on that commit.
-3. Workflow [release.yml](../.github/workflows/release.yml) builds, e2e-gates,
+3. Publish the GitHub Release for `vX.Y.Z` (not a draft).
-   and publishes `ghcr.io/mixeme/selfpost:X.Y.Z`.
+4. Workflow [release.yml](../.github/workflows/release.yml) builds, e2e-gates,
   and publishes `ghcr.io/mixeme/selfpost:X.Y.Z` (checks out tag `vX.Y.Z`).
 **GitHub Release vs GHCR.** The public [Releases](https://github.com/mixeme/selfpost/releases)
 page lists only **published** releases. A draft is visible to maintainers only —
 it looks like “no releases” to everyone else. CI does not create or publish the
 GitHub Release; you do that in the UI. Deleting a release’s git tag on GitHub
 (or re-pushing tags while cleaning the registry) converts a published release
 back into a **draft** — that matches “I published three times and it keeps
 disappearing”. After publish, leave the tag on GitHub; clean up only unwanted
 GHCR package versions, not the git tag.
 Push workflow and source changes to **github.com/mixeme/selfpost** before
 publishing — Actions reads that repo, not Gitea.
 **Gitea → GitHub tag mirror.** If every tag push from Gitea is mirrored to
 GitHub, two things follow:
 1. **GitHub Release tags must not be deleted on GitHub.** Many mirror setups
   prune remote tags that are absent on Gitea (or re-push with `--force` /
   `--prune`). Deleting `v1.0.0` / `v1.3.0` on GitHub converts a published
   Release back to draft. Mirror **branches and new tags forward**; do not
   delete release tags on the GitHub side. GHCR cleanup is package versions in
   the UI — not `git push github --delete` and not tag prune on the mirror.
 2. **Tag push runs the workflow file at that tag's commit**, not `main`. `v1.0.0`
   still points at a commit whose `release.yml` has `on: push: tags` and no
   per-arch GHCR cleanup — every mirror (re)push of that tag can republish
   `1.0.0-amd64` / `1.0.0-arm64`. Tags from `v1.3.0` onward only run
   `release.yml` on **Publish release** (`release: published`), so mirroring
   those tags alone does not start the image build.
   Safe mirror: push tags to GitHub without deleting existing ones; keep release
   tags on Gitea; publish the GitHub Release on github.com after the mirror has
   the tag.
 Ordinary commits **do not** publish an image. The compose pin and the git tag
 must match (`1.0.0` / `v1.0.0` for the first published release). Intermediate
@@ -290,26 +325,33 @@ Workflows in [.github/workflows/](../.github/workflows/). What each job runs —
 `gofmt -l` → `go vet ./...` → `go test ./...` (main module, no e2e).
-### `release.yml` — push of tag `vX.Y.Z`, or `workflow_dispatch` with SemVer
+### `release.yml` — published GitHub Release, or `workflow_dispatch` with SemVer
-`prepare` takes the version from the tag (`v1.2.5` → `1.2.5`) or from the
+Publishing a GitHub Release runs `release.yml` directly (`release: published`,
-`workflow_dispatch` `version` input. A dispatch whose ref is not a `vX.Y.Z`
+same pattern as gosentry / imap-scrub). You can also run it manually via
-tag and whose input is missing or not `X.Y.Z` fails in `prepare` — it must
+`workflow_dispatch` with an explicit `X.Y.Z` input. A bare git tag push does not
-not publish `ghcr.io/...:main`.
+run the workflow. The build always checks out `vX.Y.Z`, not `main` HEAD.
 `prepare` takes the version from `github.event.release.tag_name` on a release
 event, or from the `workflow_dispatch` `version` input. A dispatch whose input
 is missing or not `X.Y.Z` fails in `prepare`.
 ```
-prepare (version from tag or workflow_dispatch input)
+release: published
 prepare (version from release tag or workflow_dispatch input; checkout vX.Y.Z)
  → build [matrix: ubuntu-latest / ubuntu-24.04-arm]
      → docker build --load (VERSION from prepare)
      → e2e (test/e2e)
      → push ghcr.io/...:X.Y.Z-amd64 | X.Y.Z-arm64
  → merge
      → docker buildx imagetools create → unified manifest X.Y.Z
      → GitHub Packages API → drop X.Y.Z-amd64 and X.Y.Z-arm64 from GHCR
 ```
 Native per-arch matrix (no QEMU): running the full Postfix/OpenDKIM stack under
 emulation for e2e is impractical. E2e first, then push — the registry receives
-the bytes that passed the gate.
+the bytes that passed the gate. Only `ghcr.io/mixeme/selfpost:X.Y.Z` remains
 tagged in GHCR; per-arch names exist briefly during the merge job.
 A failed e2e **blocks** image publication.
@@ -3,55 +3,53 @@
 Detailed install, configuration, and day-to-day operations. For a short
 overview and quick start, see [README.md](../README.md).
 This guide has three parts: **[Installation](#installation)** (getting a
 container running with a working reverse proxy and TLS), **[Instance
 administration](#instance-administration)** (running and maintaining the
 SelfPost server itself — status, backups, users, upgrades), and **[Domain
 administration](#domain-administration)** (day-to-day work on the sending
 domains hosted on that instance — DNS, deliveries, rate limits, applications).
 ## Table of contents
- [Reverse proxy (mandatory)](#reverse-proxy-mandatory)
+- [Installation](#installation)
- [Local trial](#local-trial)
+  - [Ports](#ports)
- [Environment variables](#environment-variables)
+  - [Local trial](#local-trial)
- [DNS setup](#dns-setup)
+  - [Initial setup](#initial-setup)
- [IP warmup](#ip-warmup)
+  - [Full deployment](#full-deployment)
- [Operations](#operations)
+    - [Fixed image tag](#fixed-image-tag)
- [Rate limiting](#rate-limiting)
+  - [Environment variables](#environment-variables)
- [Backup, restore, and moving a single domain](#backup-restore-and-moving-a-single-domain)
+  - [Reverse proxy (mandatory)](#reverse-proxy-mandatory)
 - [Instance administration](#instance-administration)
  - [Status](#status)
  - [Mail queue and System log](#mail-queue-and-system-log)
  - [Settings](#settings)
  - [Users](#users)
  - [Sessions](#sessions)
  - [Upgrading](#upgrading)
  - [Container health](#container-health)
  - [Server-level DNS (PTR/rDNS)](#server-level-dns-ptrrdns)
  - [Rate limiting — level 1 (IP backstop)](#rate-limiting--level-1-ip-backstop)
  - [Full backup and restore](#full-backup-and-restore)
    - [Encrypting a backup or export](#encrypting-a-backup-or-export)
- [Published ports](#published-ports)
+- [Domain administration](#domain-administration)
- [Fixed image tag](#fixed-image-tag)
+  - [Domains page](#domains-page)
  - [Domain-level DNS (SPF, DKIM, DMARC)](#domain-level-dns-spf-dkim-dmarc)
  - [IP warmup](#ip-warmup)
  - [Rate limiting — level 2 (domain and application)](#rate-limiting--level-2-domain-and-application)
  - [Deliveries](#deliveries)
  - [Exporting and importing a single domain](#exporting-and-importing-a-single-domain)
-## Reverse proxy (mandatory)
+## Installation
-SelfPost's panel speaks plain HTTP and never terminates TLS itself — a reverse
+### Ports
 proxy in front of it is not optional. The proxy is also the project's only
 source of TLS certificates: whatever it obtains via ACME/Let's Encrypt gets
 bind-mounted **read-only** into the SelfPost container, and Postfix uses those
 same PEM files for TLS on 465 (and 587, if enabled). If the panel and the mail
 service share one hostname — the common case — it's genuinely one certificate
 serving both.
-SelfPost isn't tied to a specific proxy; pick whichever fits your host:
+`deploy/docker-compose.yml` maps **465** and **587** to the host. Port 465
 (smtps) is always active. Port **587** is published even when
 `SUBMISSION_ENABLE=false`; nothing listens until you set it to `true` — harmless,
 but it can look like an open port in external scans.
-| Proxy | Where certs live | Fragment |
+### Local trial
 |---|---|---|
 | **Apache** (default/recommended) | Host disk, via the certbot Apache plugin — PEM files ready to bind-mount, no extraction step. | [deploy/apache/selfpost-vhost.conf](../deploy/apache/selfpost-vhost.conf) |
 | nginx | Host disk, via a certbot sidecar container — same PEM-ready shape as Apache. | [deploy/nginx/](../deploy/nginx/) |
 | Caddy | Automatic ACME, zero extra containers — simplest, but its on-disk cert path is versioned internal layout, not a stable API; verify it for the Caddy version you run. | [deploy/caddy/](../deploy/caddy/) |
 | Traefik | Bundled inside `acme.json` — needs a small extraction script to produce standalone PEM files. | [deploy/traefik/](../deploy/traefik/) |
 Apache is the recommended default because the certbot Apache plugin already
 writes plain `fullchain.pem`/`privkey.pem` files to a predictable path with no
 extra moving parts between "certificate issued" and "Postfix can read it."
 **The proxy needs no security configuration of its own.** The panel emits its
 own `Content-Security-Policy`, `Strict-Transport-Security`, `X-Frame-Options`,
 `X-Content-Type-Options` and `Referrer-Policy` — deliberately, so the part
 that's easy to get wrong lives in the service rather than in a config file
 somebody edits under pressure. There is exactly one thing the proxy must do:
 **pass the original `Host` header through**. All four fragments above already
 do (Apache `ProxyPreserveHost On`, nginx `proxy_set_header Host $host`, Caddy
 and Traefik by default). A proxy that rewrites `Host` instead makes the panel
 reject every form submission as cross-origin — the log says so explicitly,
 printing the `Origin` and `Host` it compared.
 ## Local trial
 The [README quick start](../README.md#quick-start) runs a single container
 with `PANEL_COOKIE_SECURE=false` and port 8080 published on localhost. No
@@ -85,7 +83,99 @@ Add `-v /tmp/selfpost-certs:/etc/postfix/tls:ro` to the `docker run` command
 (and keep `SELFPOST_HOSTNAME=mail.local.test` so it matches the certificate CN).
 Clients must skip TLS verification — the cert is not from a public CA.
-## Environment variables
+### Initial setup
 On first start the one-time setup URL is printed in the container log
 (`docker compose logs -f`) and written to `/data/setup-token` inside the
 container — `./data/setup-token` on the host, mode `0600` — then deleted when
 setup completes. The link is `https://<SELFPOST_HOSTNAME>/setup/<token>` (path
 token, not a query string), valid for ten minutes. Open it to choose the
 administrator username and password — until then the panel has no login. If
 this host ships container logs to a central aggregator, prefer reading the
 file:
 ```sh
 docker compose exec selfpost cat /data/setup-token
 ```
 ### Full deployment
 Production layout: one `docker-compose.yml`, a `.env`, persistent `./data`, and
 TLS PEM files at `./certs` (read by Postfix on 465/587). The panel is reached
 only through a [reverse proxy](#reverse-proxy-mandatory) on 443 — port 8080 is
 bound to localhost in the default compose file.
 | Artefact | Path |
 |---|---|
 | Compose file (fixed image tag) | [deploy/docker-compose.yml](../deploy/docker-compose.yml) |
 | Environment template | [deploy/.env.example](../deploy/.env.example) |
 | Apache vhost (recommended) | [deploy/apache/selfpost-vhost.conf](../deploy/apache/selfpost-vhost.conf) |
 | nginx | [deploy/nginx/](../deploy/nginx/) |
 | Caddy | [deploy/caddy/](../deploy/caddy/) |
 | Traefik | [deploy/traefik/](../deploy/traefik/) |
 **1. Fetch the base files.**
 ```sh
 mkdir -p selfpost/data selfpost/certs && cd selfpost
 curl -O https://raw.githubusercontent.com/mixeme/selfpost/main/deploy/docker-compose.yml
 curl -O https://raw.githubusercontent.com/mixeme/selfpost/main/deploy/.env.example
 cp .env.example .env
 ```
 Edit `.env` — at minimum set `SELFPOST_HOSTNAME` to your mail hostname (bare
 FQDN, e.g. `mail.example.com`). It must match the PTR record you request from
 your provider and the certificate your proxy will obtain. See [Environment
 variables](#environment-variables) for the full list.
 **2. Reverse proxy and TLS.** Pick and set up one proxy — see [Reverse proxy
 (mandatory)](#reverse-proxy-mandatory) for the per-proxy commands. The same
 certificate must end up under `./certs` as `fullchain.pem` and `privkey.pem`
 so Postfix can serve it on 465 (and 587 if enabled).
 **3. Start SelfPost.** If you used Apache on the host (the recommended
 option), start only the base compose file from your `selfpost/` directory:
 ```sh
 docker compose up -d
 ```
 The nginx/Caddy/Traefik fragments already include `docker compose up -d` —
 skip this if you ran one of those.
 **Get the setup URL** — open it in a browser to create the admin account (see
 [Initial setup](#initial-setup)):
 ```sh
 docker compose logs selfpost 2>&1 | grep -m1 'http'
 ```
 ```sh
 cat ./data/setup-token
 ```
 **4. DNS and sending.** Before sending real mail:
 1. Confirm PTR/rDNS for the server IP points at `SELFPOST_HOSTNAME` (Status
   page → *Re-check*) — see [Server-level DNS](#server-level-dns-ptrrdns).
 2. For each domain you add in the panel, publish SPF, DKIM, and DMARC at the
   same time ([Domain-level DNS](#domain-level-dns-spf-dkim-dmarc)).
 3. Warm up a new IP gradually ([IP warmup](#ip-warmup)).
 #### Fixed image tag
 `deploy/docker-compose.yml` pins an explicit version (`ghcr.io/mixeme/selfpost:X.Y.Z`),
 deliberately never `:latest`. The current pin is `1.3.0`. Intermediate
 CHANGELOG sections (`0.2.0`…`0.6.0`) record development cuts from before that
 image was published. Pinning matters because of the backup version check (see
 [Full backup and restore](#full-backup-and-restore)): the panel binary's
 embedded version and the image tag that produced it are the same value by
 construction (the release CI stamps both from one git tag — see
 `.github/workflows/release.yml`), so the pin is what makes "restore into the
 same version" a checkable fact rather than a guess. Upgrade by bumping the tag
 deliberately, not by riding a moving target — see [Upgrading](#upgrading).
 ### Environment variables
 Copy [deploy/.env.example](../deploy/.env.example) to `.env` next to your
 `docker-compose.yml`. The table below lists every variable an operator is
@@ -95,7 +185,7 @@ expected to set; defaults match the code exactly.
 |---|---|---|---|
 | `SELFPOST_HOSTNAME` | Mail-server identity: Postfix HELO/EHLO, SASL realm, certificate CN/SAN, and the hostname the PTR check expects. Bare FQDN only — no scheme or port. | *(required)* | `.env` |
 | `SUBMISSION_ENABLE` | When `true`, also listen on port 587 with STARTTLS (RFC 6409 submission) alongside the primary 465/smtps listener. | `false` | `.env` |
-| `RATE_LIMIT_MESSAGES_PER_IP` | Level-1 backstop: maximum messages one client IP may submit per window (Postfix `smtpd_client_message_rate_limit`). See [Rate limiting](#rate-limiting). | `100` | `.env` |
+| `RATE_LIMIT_MESSAGES_PER_IP` | Level-1 backstop: maximum messages one client IP may submit per window (Postfix `smtpd_client_message_rate_limit`). See [Rate limiting — level 1](#rate-limiting--level-1-ip-backstop). | `100` | `.env` |
 | `RATE_LIMIT_WINDOW_SECONDS` | Level-1 window length in seconds (Postfix `anvil_rate_time_unit`). | `3600` | `.env` |
 | `SEND_LOG_RETENTION_DAYS` | Days of send-log history kept before the background sweep deletes rows — the main driver of `/data` growth over time. | `90` | `.env` |
 | `PANEL_SESSION_IDLE_DAYS` | Sliding idle timeout for the panel login session, in days. There is no absolute cap: an admin who keeps coming back stays signed in indefinitely. | `7` | `.env` |
@@ -106,119 +196,128 @@ TLS certificate paths (`TLS_CERT_FILE`, `TLS_KEY_FILE`) are fixed in
 [deploy/docker-compose.yml](../deploy/docker-compose.yml) to match the `./certs`
 bind mount — configure the mount, not these variables.
-**Internal variables (not part of the operator interface).** The following are
+The image also reads a number of internal, non-operator env vars (paths,
-read by the panel or startup scripts but are not meant to be changed in a
+timeouts, tuning) — not part of this interface; see
-normal deployment; documenting them here avoids treating accidental overrides as
+[architecture.md § Configuration](architecture.md#configuration) if you need
-supported configuration:
+them.
- **Panel paths and tuning:** `SELFPOST_DATA_DIR` (`/data`), `SELFPOST_DB_PATH`
+### Reverse proxy (mandatory)
  (`/data/selfpost.db`), `SELFPOST_SETUP_TOKEN_FILE`
  (`/data/setup-token`), `PANEL_HTTP_ADDR` (`:8080`),
  `JOURNAL_MILTER_SOCKET` (`/run/selfpost/journal.sock`), `MAIL_LOG`
  (`/data/log/mail.log` — read by the panel and written by Postfix, so a change
  here has to be matched in `build/postfix-config.sh`),
  `PANEL_COOKIE_SECURE` (`true`), `OPENDKIM_SOCKET`
  (`/run/opendkim/opendkim.sock`), `OPENDKIM_DIR` (`/data/opendkim`),
  `DKIM_SELECTOR_DEFAULT` (`selfpost`), `SASL_DB_PATH`
  (`/data/sasl/sasldb2`), `SASL_REALM` (defaults to `SELFPOST_HOSTNAME`),
  `POSTFIX_DIR` (`/data/postfix`), `POSTFIX_SENDER_LOGIN_MAPS`
  (`/data/postfix/sender_login_maps` — read by Postfix config only; the panel
  always writes `<POSTFIX_DIR>/sender_login_maps`, so overriding this env alone
  desyncs the map Postfix reads from the file the panel maintains).
 - **Milter and Postfix startup:** `MILTER_CONNECT_TIMEOUT` (`15s`),
  `MILTER_COMMAND_TIMEOUT` (`15s`), `MILTER_CONTENT_TIMEOUT` (`30s`),
  `MILTER_WAIT_TIMEOUT` (`30` seconds).
 - **Background maintenance:** `TLS_RELOAD_INTERVAL_SECONDS` (`86400` — daily
  `postfix reload` to pick up renewed certificates),
  `LOGROTATE_INTERVAL_SECONDS` (`21600` — check `mail.log` rotation every six
  hours; logrotate keeps 14 rotated files on a daily schedule, and each
  rotation triggers `postfix reload`).
-## DNS setup
+SelfPost's panel speaks plain HTTP and never terminates TLS itself — a reverse
 proxy in front of it is not optional. The proxy is also the project's only
 source of TLS certificates: whatever it obtains via ACME/Let's Encrypt gets
 bind-mounted **read-only** into the SelfPost container, and Postfix uses those
 same PEM files for TLS on 465 (and 587, if enabled). If the panel and the mail
 service share one hostname — the common case — it's genuinely one certificate
 serving both.
-Two different scopes — don't confuse them:
+SelfPost isn't tied to a specific proxy; pick whichever fits your host:
-**Server level (once, for the machine itself):**
+| Proxy | Where certs live | Fragment |
- **PTR/rDNS** for the server's IP, pointing at its mail hostname. Most
+|---|---|---|
-  receiving mail servers weigh this heavily; get it from whoever assigns the IP
+| **Apache** (default/recommended) | Host disk, via the certbot Apache plugin — PEM files ready to bind-mount, no extraction step. | [deploy/apache/selfpost-vhost.conf](../deploy/apache/selfpost-vhost.conf) |
-  (hosting provider's panel/support), not from your own DNS zone.
+| nginx | Host disk, via a certbot sidecar container — same PEM-ready shape as Apache. | [deploy/nginx/](../deploy/nginx/) |
 | Caddy | Automatic ACME, zero extra containers — simplest, but its on-disk cert path is versioned internal layout, not a stable API; verify it for the Caddy version you run. | [deploy/caddy/](../deploy/caddy/) |
 | Traefik | Bundled inside `acme.json` — needs a small extraction script to produce standalone PEM files. | [deploy/traefik/](../deploy/traefik/) |
-**Domain level (for *every* sending domain you add in the panel):**
+Apache is the recommended default because the certbot Apache plugin already
- **SPF** — a TXT record on the domain authorizing this server to send on its
+writes plain `fullchain.pem`/`privkey.pem` files to a predictable path with no
-  behalf (e.g. `v=spf1 a mx ip4:<server IP> -all`, adjusted to your setup).
+extra moving parts between "certificate issued" and "Postfix can read it."
 - **DKIM** — a TXT record with the exact value the panel shows on that
  domain's page (`domain page → DKIM TXT record`), one selector per domain.
 - **DMARC** — a `_dmarc` TXT record. The panel suggests `p=none` (monitoring
  only, safe to publish immediately). On a send-only relay the sending domain
  often has no inbox, so `rua=` is optional — configure a default report address
  in *Settings* or per domain when you have a mailbox that receives inbound mail
  elsewhere. If `rua=` points at another domain, publish `_report._dmarc` on that
  hub domain too; the panel checks it. Public mail hosts (Gmail, Outlook, …)
  cannot be used as external report destinations.
-Skipping any of the three per-domain records is the single most common reason
+**The proxy needs no security configuration of its own.** The panel emits its
-mail lands in spam even though SelfPost delivered it correctly — DKIM passing
+own `Content-Security-Policy`, `Strict-Transport-Security`, `X-Frame-Options`,
-doesn't help if SPF/DMARC are absent. **Whenever you add a new domain in the
+`X-Content-Type-Options` and `Referrer-Policy` — deliberately, so the part
-panel, add its DNS records at the same time**, not later.
+that's easy to get wrong lives in the service rather than in a config file
 somebody edits under pressure. There is exactly one thing the proxy must do:
 **pass the original `Host` header through**. All four fragments above already
 do (Apache `ProxyPreserveHost On`, nginx `proxy_set_header Host $host`, Caddy
 and Traefik by default). A proxy that rewrites `Host` instead makes the panel
 reject every form submission as cross-origin — the log says so explicitly,
 printing the `Origin` and `Host` it compared.
-The panel checks both scopes for you and tells you what is actually published:
+In every case the proxy terminates HTTPS for the panel; the resulting
-the *Status* page verifies the server's hostname and its reverse record
+certificate must end up under `./certs` as `fullchain.pem` and `privkey.pem`.
 (forward-confirmed reverse DNS), and each domain's page shows a *DNS status*
 card comparing the published DKIM record against the key this server signs with,
 plus the domain's SPF, DMARC, and (when configured) DMARC report-authorisation
 records. Results are cached for a few minutes;
 use *Re-check* right after publishing a record. The SPF check is deliberately
 shallow — it looks for a mechanism that literally covers this server's address
 and does not follow `include:` or `redirect=`, so a record that authorizes the
 server through an include is reported as "cannot tell" rather than as a failure.
-## IP warmup
+**Apache (recommended, on the host).** Install Apache with `ssl`, `proxy`, and
 `proxy_http` enabled. Copy
 [deploy/apache/selfpost-vhost.conf](../deploy/apache/selfpost-vhost.conf) into your
 vhost directory, replace `mail.example.com` with your hostname, enable the site,
 then issue a certificate:
-A brand-new IP has no sending history, so receiving servers are cautious with
+```sh
-it regardless of how correct your DKIM/SPF/DMARC are. Start with low volume to
+sudo certbot --apache -d mail.example.com
-a domain, increase gradually over days/weeks rather than sending everything on
+```
 day one, and check the IP against major blocklists (Spamhaus and similar)
 before and during warmup. This is inherent to how mail reputation works on the
 public internet, not something SelfPost's configuration can shortcut.
-## Operations
+Point `./certs` at the PEM files certbot wrote (symlink is fine):
 ```sh
 ln -s /etc/letsencrypt/live/mail.example.com certs
 ```
 **nginx (containerised).** From the `deploy/` directory, merge the nginx
 fragment and issue the first certificate before nginx can serve HTTPS:
 ```sh
 docker compose -f docker-compose.yml -f nginx/docker-compose.nginx.yml \
  run --rm certbot certonly --webroot -w /var/www/certbot \
  -d mail.example.com --email you@example.com --agree-tos --no-eff-email
 docker compose -f docker-compose.yml -f nginx/docker-compose.nginx.yml up -d
 ```
 Edit [deploy/nginx/nginx.conf.example](../deploy/nginx/nginx.conf.example) and
 replace `mail.example.com` first. The fragment bind-mounts certbot's output into
 both nginx and SelfPost.
 **Caddy (containerised, automatic ACME).** Edit
 [deploy/caddy/Caddyfile](../deploy/caddy/Caddyfile) and the `<hostname>` placeholders
 in [deploy/caddy/docker-compose.caddy.yml](../deploy/caddy/docker-compose.caddy.yml),
 then:
 ```sh
 docker compose -f docker-compose.yml -f caddy/docker-compose.caddy.yml up -d
 ```
 Verify Caddy's on-disk cert path for your version before relying on the
 default mount — see the comment at the top of the Caddy compose fragment.
 **Traefik (containerised).** Edit the `Host(...)` label and ACME email in
 [deploy/traefik/docker-compose.traefik.yml](../deploy/traefik/docker-compose.traefik.yml),
 start the stack, then extract PEM files for Postfix whenever Traefik issues or
 renews a certificate:
 ```sh
 docker compose -f docker-compose.yml -f traefik/docker-compose.traefik.yml up -d
 ./traefik/extract-cert.sh ./traefik/letsencrypt/acme.json mail.example.com ./traefik/extracted-certs
 ```
 Schedule `extract-cert.sh` (cron or a timer) alongside Traefik's renewals.
 ## Instance administration
 After sign-in the panel opens on **Status** — the place to answer "is the
 service healthy and will mail be accepted?"
- **Status** (`/status`) — supervised processes (Postfix, OpenDKIM, panel),
+### Status
-  TLS certificate validity and expiry, milter socket presence, and a short
+
-  Postfix queue summary. The **Machine** card adds the resource usage of the
+`/status` shows supervised processes (Postfix, OpenDKIM, panel), TLS
-  host underneath — processor (core and thread counts), memory and swap, and
+certificate validity and expiry, milter socket presence, and a short Postfix
-  per-interface network throughput and totals — read from the kernel's
+queue summary. The **Machine** card adds the resource usage of the host
-  counters; CPU and throughput are measured between refreshes, so they appear
+underneath — processor (core and thread counts), memory and swap, and
-  one refresh after the page opens. A fully busy processor or a machine out of
+per-interface network throughput and totals — read from the kernel's
-  memory is a warning here, because both delay or kill the mail path;
+counters; CPU and throughput are measured between refreshes, so they appear
-  throughput is only reported. The hostname block compares `SELFPOST_HOSTNAME`
+one refresh after the page opens. A fully busy processor or a machine out of
-  against the PTR record the internet publishes for this server's IP
+memory is a warning here, because both delay or kill the mail path;
-  (forward-confirmed reverse DNS); use *Re-check* after changing DNS. The
+throughput is only reported. The hostname block compares `SELFPOST_HOSTNAME`
-  **Reload configuration** button re-applies OpenDKIM tables and the Postfix
+against the PTR record the internet publishes for this server's IP
-  sender map from the database — use it if daemons drifted from what the panel
+(forward-confirmed reverse DNS) — see
-  shows after manual edits under `/data`.
+[Server-level DNS](#server-level-dns-ptrrdns); use *Re-check* after changing
- **Domains** (`/domains`) — add sending domains, inspect each domain's DKIM
+DNS. The **Reload configuration** button re-applies OpenDKIM tables and the
-  TXT value, SPF/DMARC checks, and SASL applications. Per-domain rate limits
+Postfix sender map from the database — use it if daemons drifted from what
-  (level 2) and trusted-IP application overrides are configured here.
+the panel shows after manual edits under `/data`.
-  *Export domain* writes a single-domain archive;
+
-  *Import a domain* on the Backup page reads one back in.
+### Mail queue and System log
- **Deliveries** (`/deliveries`) — searchable send log with server-side filters
+
  by domain and application. A row identifies its message and nothing more —
  time, sender, recipient, subject and status `queued` (accepted, not yet
  delivered), `sent` (handed off successfully), `deferred` (Postfix is retrying),
  `bounced` (final failure), or `rejected` (refused — for example by a level-2
  rate limit); *Details* opens that row's own page
  (`/deliveries/{id}`). That page carries the sending domain, the application it
  was submitted under, the Postfix queue id and the journal id, beside the
  message's history — when it was accepted and what Postfix later reported for
  the recipient — and, under both, the `mail.log` lines for its queue id: the
  connection to the receiving server, the server's reply, and the status that
  reply was filed as. Rows outlive `mail.log`, so an older message's lines may
  have rotated away; the page says so. Retention is controlled by
  `SEND_LOG_RETENTION_DAYS`.
 - **Mail queue** (`/mail-queue`) — live view of messages Postfix is still
  trying to deliver or deferring.
 - **System log** (`/system-log`) — tail of `/data/log/mail.log` (Postfix and
@@ -227,69 +326,88 @@ service healthy and will mail be accepted?"
  hours. It lives in the data volume, so it survives a container recreate along
  with the rest of the state — `./data/log/` on the host — but it is *not*
  included in backups: it is diagnostics, not state.
- **Backup** (`/backup`) — download a full-server backup; the same page hosts
+
-  the domain-import form (`POST /domains/import`). See
+### Settings
-  [Backup, restore, and moving a single domain](#backup-restore-and-moving-a-single-domain).
+
- **Settings** (`/settings`) — change the administrator username and/or
+`/settings` changes the signed-in user's username and/or password. **Global
-  password, and the panel-wide default DMARC report address (`rua=`) offered
+administrators** also set the panel-wide default DMARC report address (`rua=`)
-  when a domain doesn't set its own — see [DNS setup](#dns-setup). Application
+offered when a domain doesn't set its own — see
-  SASL logins are separate and are not changed here.
+[Domain-level DNS](#domain-level-dns-spf-dkim-dmarc). Application SASL logins
- **Users** (`/users`, global administrator only) — create, edit, and delete
+are separate and are not changed here.
-  panel users. There are two roles:
+
-  - **Global administrator** — full access to every page and every domain,
+### Users
 `/users` (global administrator only) creates, edits, and deletes panel users.
 There are two roles:
 - **Global administrator** — full access to every page and every domain,
  including Users, Backup, Status, Mail queue, and System log.
-  - **Domain-admin** — scoped to one or more domains assigned by a global
+- **Domain-admin** — scoped to one or more domains assigned by a global
  administrator. Sees only those domains' pages, applications, and
-    Deliveries rows; `/users`, `/backup`, `/status`, `/mail-queue`, and
+  Deliveries rows; cannot add or delete domains. `/users`, `/backup`,
-    `/system-log` are not reachable (404). A domain-admin can *export* the
+  `/status`, `/mail-queue`, `/system-log`, and `POST /reload` are not
-    domains assigned to them — see the note on working credentials below.
+  reachable (404). A domain-admin can *export* the
  domains assigned to them — see
  [Exporting and importing a single domain](#exporting-and-importing-a-single-domain).
-  The panel refuses to remove or demote the **last** global administrator, so
+The panel refuses to remove or demote the **last** global administrator, so
-  it can never end up with none.
+it can never end up with none.
-**Sessions.** A login survives a container restart: sessions live in SQLite, not
+### Sessions
-in memory. Expiry is a sliding idle window (`PANEL_SESSION_IDLE_DAYS`, default
+
 A login survives a container restart: sessions live in SQLite, not in
 memory. Expiry is a sliding idle window (`PANEL_SESSION_IDLE_DAYS`, default
 seven days) with no absolute lifetime cap — an admin who keeps using the panel
 stays signed in indefinitely. HTMX polling on the monitoring screens
 (Deliveries, Mail queue, System log, and the Status health fragment) does
 **not** count as activity, so an auto-refreshing tab left open will not keep a
-session alive forever. Changing the password signs out every other session but
+session alive forever. Changing **your own** password on `/settings` signs out
-leaves the current browser signed in.
+every other session for that user but leaves the current browser signed in.
 Signing out (`POST /logout`) ends only the current session — other browsers or
 tabs for the same user keep working until their session rows expire.
-**Upgrading.** Bump the pinned image tag in `docker-compose.yml` to the target
+### Upgrading
-release, then `docker compose up -d`. The backup version check requires the
+
-running image to match the version that created a full backup — see [Fixed image
+Bump the pinned image tag in `docker-compose.yml` to the target release, then
 `docker compose up -d`. The backup version check requires the running image
 to match the version that created a full backup — see [Fixed image
 tag](#fixed-image-tag).
-**Container health.** The image declares a Docker `HEALTHCHECK` that probes
+### Container health
 `GET /healthz` on port 8080 (unauthenticated). It returns `200 ok` when
 OpenDKIM, the panel, and Postfix are all `RUNNING` under supervisord;
 otherwise `503 unhealthy`. This catches a dead mail path that would still leave
 the HTTP server up, but it does **not** verify TLS certificates, DNS records,
 or end-to-end delivery — use the authenticated **Status** page for that. External
 monitoring can use the same endpoint through the reverse proxy if you expose it,
 or poll `docker inspect` health state on the host.
-**First-time setup link.** On first start the one-time setup URL is printed in
+The image declares a Docker `HEALTHCHECK` that probes `GET /healthz` on port
-the container log (`docker compose logs -f`) and written to `/data/setup-token`
+8080 (unauthenticated). It returns `200 ok` when OpenDKIM, the panel, and
-inside the container — `./data/setup-token` on the host, mode `0600` — then
+Postfix are all `RUNNING` under supervisord; otherwise `503 unhealthy`. This
-deleted when setup completes. The link is
+catches a dead mail path that would still leave the HTTP server up, but it
-`https://<SELFPOST_HOSTNAME>/setup/<token>` (path token, not a query string),
+does **not** verify TLS certificates, DNS records, or end-to-end delivery —
-valid for ten minutes. If this host ships container logs to a central
+use the authenticated [Status](#status) page for that. External monitoring
-aggregator, prefer reading the file:
+can use the same endpoint through the reverse proxy if you expose it, or poll
 `docker inspect` health state on the host.
-```sh
+### Server-level DNS (PTR/rDNS)
 docker compose exec selfpost cat /data/setup-token
 ```
-## Rate limiting
+Once, for the machine itself: **PTR/rDNS** for the server's IP, pointing at
 its mail hostname. Most receiving mail servers weigh this heavily; get it
 from whoever assigns the IP (hosting provider's panel/support), not from
 your own DNS zone.
-SelfPost applies two independent layers; both can refuse a submission, but only
+The [Status](#status) page verifies the server's hostname against this
-level 2 writes a `rejected` row in the send log. Level-2 ceilings set in the
+record (forward-confirmed reverse DNS). Results are cached for about one
-panel cannot exceed level 1 (the panel shows the level-1 values and rejects
+minute; use *Re-check* right after publishing a record.
 higher numbers).
-**Level 1 (IP backstop)** — always on, configured via `.env`:
+Per-domain DNS (SPF, DKIM, DMARC) is a separate scope — see
 [Domain-level DNS](#domain-level-dns-spf-dkim-dmarc).
 ### Rate limiting — level 1 (IP backstop)
 SelfPost applies two independent layers of rate limiting; both can refuse a
 submission, but only level 2 (domain/application, see
 [Domain administration](#rate-limiting--level-2-domain-and-application))
 writes a `rejected` row in the send log. Level-2 ceilings set in the panel
 cannot exceed level 1 (the panel shows the level-1 values and rejects higher
 numbers).
 Level 1 is always on, configured via `.env`:
 - `RATE_LIMIT_MESSAGES_PER_IP` → Postfix `smtpd_client_message_rate_limit`
 - `RATE_LIMIT_WINDOW_SECONDS` → Postfix `anvil_rate_time_unit`
@@ -297,81 +415,117 @@ higher numbers).
 This is an anvil limit per connecting client IP. It keeps working even if the
 journal-milter (level 2) is down. There is no per-IP bypass.
-**Level 2 — domain** — optional, on each domain's page. A message ceiling and
+### Full backup and restore
 window for **every** client IP sending as that domain. When unset, only
 level 1 applies for non-privileged senders.
-**Level 2 — application (trusted IPs)** — optional override on an application:
+**Full backup** (whole `/data` except `log/`: SQLite, all domains' DKIM keys,
-list one or more client IPs and a ceiling **strictly above** the domain limit
+all applications' SASL credentials, `manifest.json` with the version that
-(still ≤ level 1). Connections from those IPs use the application ceiling and
+created it): panel button (*Backup* → *Full backup*), or from the host:
 skip the domain check. Other IPs stay under the domain limit (or level 1 alone).
 An application override without trusted IPs is inactive.
-When a level-2 ceiling is exceeded, Postfix returns a 4xx and the refusal is
+```sh
-recorded in Deliveries as `rejected`.
+docker exec <container> selfpost-backup > selfpost-backup.tar.gz
 ```
-**Level 2 is best-effort, not a guarantee.** It runs inside the journal-milter
+**Restore** means unpacking that archive into a fresh `/data` bind mount and
-and is deliberately fail-open: if the rate-limit lookup hits a store error, or
+starting a container of the **exact same image version** that created it —
-the connecting client's IP is not available to the milter, level 2 is skipped
+SelfPost refuses to start otherwise and tells you which tag to use. On the
-and the message is accepted rather than held up. Level 1 (the Postfix anvil
+first successful start after restore, `manifest.json` from the archive is
-limit above) is the backstop that keeps working even when level 2 cannot run.
+**deleted** — it guards only that one boot, so a later in-place upgrade is
 not blocked. On that same first boot the panel also runs one **Resync** —
 OpenDKIM's tables and Postfix's sender map are re-derived from SQLite and both
 daemons are reloaded, healing any drift between the extracted files and the
 database (the Status page's *Reload configuration* button runs the same step
 on demand). This is why the compose file pins a fixed tag rather than
 `:latest`: without a known version, there'd be no way to tell which image
 restoring a given backup actually requires (see [Fixed image
 tag](#fixed-image-tag)).
-## Backup, restore, and moving a single domain
+**Restoring in place** (same host — recovering from data loss, or rolling
 back after a bad change):
-Two related but distinct operations
+```sh
-([architecture.md](architecture.md) § Persistence):
+# 1. Stop the instance being replaced
 docker compose down
- **Full backup** (whole `/data` except `log/`: SQLite, all domains' DKIM keys,
+# 2. Move the current /data aside rather than deleting it, start from empty
-  all applications' SASL credentials, `manifest.json` with the version that
+mv ./data ./data.before-restore
-  created it): panel button (*Backup* → *Full backup*), or from the
+mkdir ./data
  host:
  ```sh
  docker exec <container> selfpost-backup > selfpost-backup.tar.gz
  ```
  **Restore** means unpacking that archive into a fresh `/data` bind mount and
  starting a container of the **exact same image version** that created it —
  SelfPost refuses to start otherwise and tells you which tag to use. On the
  first successful start after restore, `manifest.json` from the archive is
  **deleted** — it guards only that one boot, so a later in-place upgrade is
  not blocked. This is why the compose file pins a fixed tag rather than
  `:latest`: without a known version, there'd be no way to tell which image
  restoring a given backup actually requires.
-  Restoring an archive taken **before** you invalidated a session (password
+# 3. Unpack the backup into the fresh directory
-  change, logout everywhere) can bring that session back: session rows travel
+tar xzf selfpost-backup.tar.gz -C ./data
  with the backup, and a browser that still holds the matching cookie is
  logged in again once the idle timeout allows it. If a restore might do this,
  changing every user's password afterwards clears it out.
-  **Alternative: archive `./data` while stopped.** If the service can be taken
+# 4. docker-compose.yml must already pin the exact tag the backup was made
-  offline, `docker compose down` then `tar czf selfpost-data.tar.gz ./data` on
+#    with — check the archive's manifest if unsure:
-  the host is safe — nothing is writing to SQLite. Unlike the panel/CLI backup
+tar xzf selfpost-backup.tar.gz -O manifest.json
  this sweeps in `./data/log/` too, which is Postfix's raw log and usually the
  bulk of the archive; add `--exclude=./data/log` if you only want the state.
  Do **not** tar `./data` while
  the container is running: the database uses WAL mode and a naive copy can
  capture an inconsistent snapshot. The panel/CLI backup remains preferable when
  you cannot afford downtime because it takes a consistent SQLite snapshot via
  the Backup API on a live container.
- **Export/import a single domain** (domain page → *Export domain* to write the
+# 5. Start it and watch the boot
-  file, *Backup* → *Import a domain* to read it back in): moves one domain — its DKIM key and its applications' **working**
+docker compose up -d
-  SASL passwords — to a different SelfPost instance without regenerating
+docker compose logs -f selfpost
-  anything, so DNS (the DKIM TXT record) doesn't need to change. Unlike a full
+```
  restore, this works across different hostnames/instances. *Import* is
  global-administrator only; *export* is available to any user who can access
  the domain, **including a domain-admin** for a domain assigned to them — so
  a domain-admin can walk away with that domain's working SASL passwords in
  the clear. Weigh that when deciding which domains to assign to a
  domain-admin account.
-Both files are **secrets** — they contain the admin password hash (full
+A version mismatch at step 5 refuses to start and leaves `/data` untouched —
-backup) or working application credentials (domain export) in the clear or in
+the panel exits with a message naming the tag to use, e.g.:
 directly reversible form. Treat them like any other credential material:
 restrict who can read them, don't email them around — and encrypt them, which
 SelfPost can do for you.
-### Encrypting a backup or export
+```
 backup: this backup was created by SelfPost 1.2.3 but this image is 1.3.0 — restore into the matching image (selfpost:1.2.3)
 ```
 Fix the tag in `docker-compose.yml`, `docker compose pull && docker compose up
 -d` again — the manifest is still there because the failed boot never got to
 delete it.
 **Moving to a different host** is the same five steps, just starting cold:
 bring the compose files and the correct pinned image tag to the new host
 (step 1 of [Full deployment](#full-deployment)), put the backup archive in
 place of step 3 above, then redo the reverse-proxy/TLS and DNS steps of a
 [Full deployment](#full-deployment) — the PTR record and the certificate both
 belong to the old IP/host and have to be reissued for the new one; nothing in
 the backup carries them.
 **Restoring an encrypted (`.spbk`) backup** needs a running container to
 decrypt it first — any container with the `selfpost-backup` CLI works; decryption
 does not read `/data` and performs no version check. Start one normally
 (step 5, but on an empty `/data` you haven't unpacked yet), then:
 ```sh
 docker exec -i <container> selfpost-backup -decrypt < backup.spbk > selfpost-backup.tar.gz
 ```
 Stop it, wipe `/data` again, and continue from step 2 above with the
 resulting `.tar.gz` — see [Encrypting a backup or
 export](#encrypting-a-backup-or-export) for the decrypt command's password
 options.
 Restoring an archive taken **before** a session row was removed can bring
 that session back: session rows travel with the backup, and a browser that
 still holds the matching cookie is signed in again on the next request if the
 restored row's idle expiry has not passed. `POST /logout` removes only the
 current session; there is no "logout everywhere". Changing your own password
 on `/settings` deletes your other sessions, but a global administrator
 resetting another user's password on `/users` does not invalidate that user's
 existing sessions.
 **Alternative: archive `./data` while stopped.** If the service can be taken
 offline, `docker compose down` then `tar czf selfpost-data.tar.gz ./data` on
 the host is safe — nothing is writing to SQLite. Unlike the panel/CLI backup
 this sweeps in `./data/log/` too, which is Postfix's raw log and usually the
 bulk of the archive; add `--exclude=./data/log` if you only want the state.
 Do **not** tar `./data` while the container is running: the database uses
 WAL mode and a naive copy can capture an inconsistent snapshot. The
 panel/CLI backup remains preferable when you cannot afford downtime because
 it takes a consistent SQLite snapshot via the Backup API on a live
 container.
 See also [Exporting and importing a single
 domain](#exporting-and-importing-a-single-domain) — a different, domain-scoped
 operation that also lives on the *Backup* page (`/backup`).
 Both a full backup and a domain export are **secrets** — they contain the
 admin password hash (full backup) or working application credentials (domain
 export) in the clear or in directly reversible form. Treat them like any
 other credential material: restrict who can read them, don't email them
 around — and encrypt them, which SelfPost can do for you.
 #### Encrypting a backup or export
 Both download forms carry an **Encrypt with a password** checkbox. Ticked, the
 file that comes down is an encrypted envelope instead of the plain archive:
@@ -411,21 +565,121 @@ docker exec -e SELFPOST_BACKUP_PASSWORD="$PW" <container> selfpost-backup > back
 With no password set, the CLI keeps writing the plain `.tar.gz` it always has.
-## Published ports
+## Domain administration
-`deploy/docker-compose.yml` maps **465** and **587** to the host. Port 465
+### Domains page
 (smtps) is always active. Port **587** is published even when
 `SUBMISSION_ENABLE=false`; nothing listens until you set it to `true` — harmless,
 but it can look like an open port in external scans.
-## Fixed image tag
+`/domains` lists sending domains and hosts the add-domain form (**global
 administrator only**). Domain administrators see only domains assigned to
 them. Each row shows its DKIM TXT value, SPF/DMARC checks, and SASL
 applications. Per-domain rate limits (level 2) and trusted-IP application
 overrides are configured here — see [Rate limiting —
 level 2](#rate-limiting--level-2-domain-and-application). *Export domain*
 writes a single-domain archive; *Import a domain* on the Backup page reads
 one back in (**global administrator only**) — see [Exporting and importing a single
 domain](#exporting-and-importing-a-single-domain).
-`deploy/docker-compose.yml` pins an explicit version (`ghcr.io/mixeme/selfpost:X.Y.Z`),
+### Domain-level DNS (SPF, DKIM, DMARC)
-deliberately never `:latest`. The current pin is `1.2.5`. Intermediate
+
-CHANGELOG sections (`0.2.0`…`0.6.0`) record development cuts from before that
+For *every* sending domain you add in the panel:
-image was published. Pinning matters because of the backup version check above:
+
-the panel binary's embedded version and the image tag that produced it are the
+- **SPF** — a TXT record on the domain authorizing this server to send on its
-same value by construction (the release CI stamps both from one git tag — see
+  behalf (e.g. `v=spf1 a mx ip4:<server IP> -all`, adjusted to your setup).
-`.github/workflows/release.yml`), so the pin is what makes "restore into the
+- **DKIM** — a TXT record with the exact value the panel shows on that
-same version" a checkable fact rather than a guess. Upgrade by bumping the tag
+  domain's page (`domain page → DKIM TXT record`), one selector per domain.
-deliberately, not by riding a moving target.
+- **DMARC** — a `_dmarc` TXT record. The panel suggests `p=none` (monitoring
  only, safe to publish immediately). On a send-only relay the sending domain
  often has no inbox, so `rua=` is optional — configure a default report address
  in *Settings* (see [Settings](#settings)) or per domain when you have a
  mailbox that receives inbound mail elsewhere. If `rua=` points at another
  domain, publish `_report._dmarc` on that hub domain too; the panel checks
  it. Public mail hosts (Gmail, Outlook, …) cannot be used as external
  report destinations.
 Skipping any of the three records is the single most common reason mail
 lands in spam even though SelfPost delivered it correctly — DKIM passing
 doesn't help if SPF/DMARC are absent. **Whenever you add a new domain in the
 panel, add its DNS records at the same time**, not later.
 Each domain's page shows a *DNS status* card comparing the published DKIM
 record against the key this server signs with, plus the domain's SPF,
 DMARC, and (when configured) DMARC report-authorisation records. Results are
 cached for a few minutes; use *Re-check* right after publishing a record.
 The SPF check is deliberately shallow — it looks for a mechanism that
 literally covers this server's address and does not follow `include:` or
 `redirect=`, so a record that authorizes the server through an include is
 reported as "cannot tell" rather than as a failure.
 Server-level DNS (the PTR/rDNS record) is a separate, once-per-machine scope
 — see [Server-level DNS](#server-level-dns-ptrrdns).
 ### IP warmup
 A brand-new IP has no sending history, so receiving servers are cautious with
 it regardless of how correct your DKIM/SPF/DMARC are. Start with low volume to
 a domain, increase gradually over days/weeks rather than sending everything on
 day one, and check the IP against major blocklists (Spamhaus and similar)
 before and during warmup. This is inherent to how mail reputation works on the
 public internet, not something SelfPost's configuration can shortcut.
 ### Rate limiting — level 2 (domain and application)
 Level 2 is optional, configured on each domain's page, and layers on top of
 the always-on [level-1 IP backstop](#rate-limiting--level-1-ip-backstop).
 Level-2 ceilings cannot exceed level 1 (the panel shows the level-1 values
 and rejects higher numbers). When a level-2 ceiling is exceeded, Postfix
 returns a 4xx and the refusal is recorded in [Deliveries](#deliveries) as
 `rejected`.
 **Level 2 — domain** — a message ceiling and window for **every** client IP
 sending as that domain. When unset, only level 1 applies for non-privileged
 senders.
 **Level 2 — application (trusted IPs)** — optional override on an
 application: list one or more client IPs and a ceiling **strictly above**
 the domain limit (still ≤ level 1). Connections from those IPs use the
 application ceiling and skip the domain check. Other IPs stay under the
 domain limit (or level 1 alone). An application override without trusted
 IPs is inactive.
 **Level 2 is best-effort, not a guarantee.** It runs inside the
 journal-milter and is deliberately fail-open: if the rate-limit lookup hits
 a store error, or the connecting client's IP is not available to the
 milter, level 2 is skipped and the message is accepted rather than held up.
 Level 1 is the backstop that keeps working even when level 2 cannot run.
 ### Deliveries
 `/deliveries` is a searchable send log with server-side filters by domain
 and application. A row identifies its message and nothing more — time,
 sender, recipient, subject and status `queued` (accepted, not yet
 delivered), `sent` (handed off successfully), `deferred` (Postfix is
 retrying), `bounced` (final failure), or `rejected` (refused — for example
 by a [level-2 rate limit](#rate-limiting--level-2-domain-and-application));
 *Details* opens that row's own page (`/deliveries/{id}`). That page carries
 the sending domain, the application it was submitted under, the Postfix
 queue id and the journal id, beside the message's history — when it was
 accepted and what Postfix later reported for the recipient — and, under
 both, the `mail.log` lines for its queue id: the connection to the
 receiving server, the server's reply, and the status that reply was filed
 as. Rows outlive `mail.log`, so an older message's lines may have rotated
 away; the page says so. Retention is controlled by
 `SEND_LOG_RETENTION_DAYS`.
 ### Exporting and importing a single domain
 Domain page → *Export domain* to write the file, *Backup* → *Import a
 domain* to read it back in. This moves one domain — its DKIM key and its
 applications' **working** SASL passwords — to a different SelfPost instance
 without regenerating anything, so DNS (the DKIM TXT record) doesn't need to
 change. Unlike a full restore (see [Full backup and
 restore](#full-backup-and-restore)), this works across different
 hostnames/instances. *Import* is global-administrator only; *export* is
 available to any user who can access the domain, **including a domain-admin**
 for a domain assigned to them — so a domain-admin can walk away with that
 domain's working SASL passwords in the clear. Weigh that when deciding which
 domains to assign to a domain-admin account.
 A domain export is a secret in the same way a full backup is, and can be
 encrypted the same way — see [Encrypting a backup or
 export](#encrypting-a-backup-or-export).
@@ -198,7 +198,7 @@ domain-admin's browser sending a request still needs that domain-admin's own
 cookie, so a token would not add a boundary between roles that the
 authorization checks (`Principal.CanAccessDomain`,
 [internal/web/auth/principal.go](../internal/web/auth/principal.go); route
-gating in [internal/web/auth/middleware.go](../internal/web/auth/middleware.go))
+gating in [internal/web/handlers/authz.go](../internal/web/handlers/authz.go))
 don't already enforce. The remaining case is an external site making a
 logged-in user's browser send a request, which the origin check covers without
 touching a single template.
Author	SHA1	Message	Date
mix	2f888dc7be	ci: drop per-arch GHCR tags via GitHub Packages API test / test (push) Has been cancelled Details imagetools has no rm subcommand; the merge cleanup had been failing silently. Document Gitea-to-GitHub tag mirror pitfalls in development.md. CHANGELOG [1.3.0] updated. Co-Authored-By: Cursor <cursoragent@cursor.com>	2026-08-15 22:57:34 +03:00
mix	5598b62e4e	release: 1.3.0 test / test (push) Has been cancelled Details Close Unreleased for security, tests, docs, and release CI; pin compose and docs to 1.3.0. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-14 21:51:29 +03:00
mix	32f5085c48	docs: record release CI workflow changes in [Unreleased] The three post-1.2.5 CI commits that tie image publish to a published GitHub Release and trim per-arch GHCR tags were missing from the changelog. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-14 21:47:09 +03:00
mix	5601f73622	ci: consolidate release workflow and trim GHCR tags test / test (push) Has been cancelled Details Run release.yml directly on release:published instead of a dispatcher workflow. Remove per-arch tags from GHCR after the manifest merge so only X.Y.Z remains visible to operators. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-14 21:44:33 +03:00
mix	e17b1680bd	ci: dispatch release build from release-on-publish workflow test / test (push) Has been cancelled Details GitHub recorded release published at 16:44:21Z but no release.yml run started. A thin release-on-publish workflow listens for publish and starts release.yml via workflow_dispatch (always creates a run). release.yml now checks out vX.Y.Z from the version input, not main HEAD. Co-Authored-By: Cursor <cursoragent@cursor.com>	2026-08-14 19:48:20 +03:00
mix	5b63da0e49	ci: trigger release workflow on published GitHub Release test / test (push) Has been cancelled Details Bare git tag pushes no longer start the image build; publishing a GitHub Release does. workflow_dispatch still requires an explicit X.Y.Z version. Docs explain draft vs published releases and that deleting a tag on GitHub converts a published release back to draft. Co-Authored-By: Cursor <cursoragent@cursor.com>	2026-08-14 19:43:06 +03:00
mix	e9aaed1c7b	docs: reconcile [Unreleased] with full git history since 1.2.5 test / test (push) Has been cancelled Details Expand the doc-alignment entry to cover guide RBAC and restore Resync wording; trim the P2 entry of claims superseded by that pass while keeping its /license route-table addition with a cross-reference. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-14 19:40:46 +03:00
mix	1bd71c10d0	docs: align operator docs with routes, sessions, and restore test / test (push) Has been cancelled Details Fix architecture route RBAC, restore Resync, and session/password wording; correct guide restore/session/PTR claims and README port-587 text; point the CSRF ADR at authz.go for global route gating. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-14 19:36:24 +03:00
mix	74acf09212	docs: verify [Unreleased] against git since 1.2.5 test / test (push) Has been cancelled Details Move restore Resync under Fixed to match `e70ba90`, and extend the restore test bullet with the resync boot step and TestResyncAfterRestoreHealsDriftedMaps. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-14 19:30:12 +03:00
mix	ba07decbb0	docs: bring [Unreleased] up to date with guide and review closure Record the operator-guide restructure, merge the stale code-review plan entry with its completion note, and align the restore Resync bullet with the current backup package comment. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-14 19:24:29 +03:00
mix	4fc5cff266	docs(guide): add worked restore commands to Full backup and restore test / test (push) Has been cancelled Details The section explained what a restore means conceptually but gave no runnable commands. Add a step-by-step in-place restore, a move-to-a-new-host variant, and the encrypted-backup decrypt-first sequence, plus the actual version-mismatch error text so operators know what to expect. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-08-14 19:18:54 +03:00
mix	ac8c2af500	docs(guide,architecture): move internal env vars out of the operator guide test / test (push) Has been cancelled Details Internal (non-operator) env vars were listed in guide.md's Environment variables section even though the guide's own text says operators aren't meant to touch them. They now live in architecture.md § Configuration, the as-built/internals doc; guide.md keeps a one-line pointer. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-08-14 19:13:33 +03:00
mix	9e3f0d0fad	docs(guide): reorder Installation and add a Full deployment walkthrough test / test (push) Has been cancelled Details Installation now reads Ports, Local trial, Initial setup, Full deployment (with Fixed image tag nested under it), Environment variables, Reverse proxy. The step-by-step production deploy and the per-proxy TLS commands move from README's "Reference deploy" into the operator guide; README keeps a short pointer instead of duplicating the walkthrough. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-08-14 15:49:58 +03:00
mix	403c76d17d	docs(guide): restructure into Installation / Instance admin / Domain admin test / test (push) Has been cancelled Details Splits mixed DNS-setup, Operations, Rate-limiting, and Backup sections along the instance/domain boundary and fixes README anchors that pointed at the old #dns-setup heading. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-08-14 15:45:38 +03:00