Phase 9: full backup/restore + domain export/import (spec 7.5, 11.6)

Full server backup (spec 7.5.A): internal/backup produces a tar.gz of all of
/data — a consistent SQLite snapshot via VACUUM INTO, DKIM keys, sasldb2 and a
version manifest; TLS certs (tls/) and the Postfix queue are excluded. Two equal
paths: the panel button (POST /backup, no-store) and the selfpost-backup CLI via
docker exec (spec 11.6). CheckRestore runs before store.Open: a manifest version
mismatch refuses to boot with the image tag to use; a match consumes the
manifest so it only guards the first post-restore boot. Restore is not a
separate branch — Postfix/OpenDKIM regenerate from the restored SQLite as on any
start.

Domain export/import (spec 7.5.B): DomainExport carries the DKIM private key and
each application's working password. SASL secrets are read from sasldb2 via
db_dump (the userPassword property is plaintext) and, on import, re-keyed under
the local realm with saslpasswd2 — so credentials keep working on an instance
with a different hostname, with no DKIM DNS change. Import validates and rolls
back atomically on any failure. db-util (db_dump) is now an explicit image dep.

Verified on the server (selfpost:p9): gofmt/vet/test green; container e2e for
cross-realm domain export/import (SMTP AUTH 235 under the new realm), CLI and
panel backups, same-version restore, and version-mismatch refusal.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

internal/web/handlers_apps.go

@@ -144,6 +144,8 @@ func detailFlash(r *http.Request) string {
 		return "Application address mode updated."
 	case r.URL.Query().Get("ratelimit") != "":
 		return "Rate limit updated."
+	case r.URL.Query().Get("imported") != "":
+		return "Domain imported. Its DKIM DNS record is unchanged — no DNS update is needed."
 	default:
 		return ""
 	}

internal/web/handlers_backup.go

@@ -0,0 +1,133 @@
+package web
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+
+	"codeberg.org/mix/selfpost/internal/backup"
+	"codeberg.org/mix/selfpost/internal/domain"
+	"codeberg.org/mix/selfpost/internal/store"
+)
+
+// maxImportBytes caps a domain-import upload. A domain export is a small JSON
+// document (a DKIM key and a handful of credentials); this leaves generous head
+// room while refusing anything large enough to be an abuse attempt.
+const maxImportBytes = 1 << 20 // 1 MiB
+
+// handleBackup streams a full-server backup as a download (spec 7.5.A). It is an
+// authenticated admin action (this handler sits behind the auth middleware). The
+// archive carries DKIM private keys, the admin password hash and SASL
+// credentials, so it is served with no-store and as an attachment to discourage
+// caching of secret material.
+func (s *Server) handleBackup(w http.ResponseWriter, r *http.Request) {
+	filename := fmt.Sprintf("selfpost-backup-%s.tar.gz", time.Now().UTC().Format("20060102-150405"))
+
+	w.Header().Set("Content-Type", "application/gzip")
+	w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=%q", filename))
+	w.Header().Set("Cache-Control", "no-store")
+
+	if err := backup.Create(w, backup.Params{
+		DataDir: s.cfg.DataDir,
+		DBPath:  s.cfg.DBPath,
+		Version: s.cfg.Version,
+	}); err != nil {
+		// Headers (and possibly some bytes) may already be on the wire, so we
+		// cannot switch to a clean error page; log it and let the truncated
+		// download fail loudly on the client side.
+		logf("panel: full backup failed: %v", err)
+		return
+	}
+}
+
+// handleExportDomain streams a single-domain export as a secret download (spec
+// 7.5.B). Like the full backup it is POST-only (state is not changed, but the
+// response contains the domain's DKIM private key and application passwords, so
+// it must not be prefetchable or cached).
+func (s *Server) handleExportDomain(w http.ResponseWriter, r *http.Request) {
+	d, ok := s.lookupDomain(w, r)
+	if !ok {
+		return
+	}
+	exp, err := s.domains.Export(d.ID)
+	if err != nil {
+		logf("panel: export domain %d: %v", d.ID, err)
+		http.Error(w, "export failed", http.StatusInternalServerError)
+		return
+	}
+	body, err := json.MarshalIndent(exp, "", "  ")
+	if err != nil {
+		logf("panel: export domain %d: encode: %v", d.ID, err)
+		http.Error(w, "export failed", http.StatusInternalServerError)
+		return
+	}
+
+	filename := fmt.Sprintf("selfpost-domain-%s.json", d.Name)
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=%q", filename))
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = w.Write(body)
+}
+
+// handleImportDomain accepts an uploaded domain-export file and re-creates the
+// domain on this instance (spec 7.5.B). The domain name is normalised and
+// validated here (spec 7.6.2); the domain service validates the selector, each
+// login and address, and the DKIM key before writing anything. On success it
+// redirects to the new domain's page; on failure it re-renders the dashboard
+// with a friendly message.
+func (s *Server) handleImportDomain(w http.ResponseWriter, r *http.Request) {
+	r.Body = http.MaxBytesReader(w, r.Body, maxImportBytes)
+	if err := r.ParseMultipartForm(maxImportBytes); err != nil {
+		s.renderDashboard(w, r, http.StatusBadRequest, "", "", "Could not read the uploaded file (too large or not a valid upload).")
+		return
+	}
+	file, _, err := r.FormFile("file")
+	if err != nil {
+		s.renderDashboard(w, r, http.StatusBadRequest, "", "", "Choose a domain export file to import.")
+		return
+	}
+	defer file.Close()
+
+	var exp domain.DomainExport
+	dec := json.NewDecoder(file)
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(&exp); err != nil {
+		s.renderDashboard(w, r, http.StatusBadRequest, "", "", "That file is not a valid SelfPost domain export.")
+		return
+	}
+
+	// Normalise and validate the domain name before it reaches the service, the
+	// same gate the add-domain form uses (spec 7.6.2).
+	exp.Domain = normalizeDomain(exp.Domain)
+	if err := validateDomain(exp.Domain); err != nil {
+		s.renderDashboard(w, r, http.StatusBadRequest, "", "", "Invalid domain in export file: "+err.Error())
+		return
+	}
+
+	d, err := s.domains.Import(exp)
+	if err != nil {
+		logf("panel: import domain %q: %v", exp.Domain, err)
+		status, msg := importErrorMessage(err)
+		s.renderDashboard(w, r, status, "", "", msg)
+		return
+	}
+	http.Redirect(w, r, fmt.Sprintf("/domains/%d?imported=1", d.ID), http.StatusSeeOther)
+}
+
+// importErrorMessage maps a domain-import failure (already logged by the caller)
+// to an HTTP status and a user-facing message. Duplicate domain/login are called
+// out specifically; other failures — validation errors describing what is wrong
+// with the file, or an internal write/reload problem — are surfaced verbatim to
+// this admin-only panel so the operator can act on them.
+func importErrorMessage(err error) (int, string) {
+	switch {
+	case errors.Is(err, store.ErrDomainExists):
+		return http.StatusConflict, "A domain with that name already exists here. Delete it first, or import into a fresh instance."
+	case errors.Is(err, store.ErrLoginExists):
+		return http.StatusConflict, "One of the application logins in the file is already in use on this instance. Application logins must be unique across all domains."
+	default:
+		return http.StatusBadRequest, "Could not import the domain: " + err.Error()
+	}
+}

internal/web/handlers_domains.go

@@ -13,13 +13,14 @@ import (
 // domains with their DKIM/selector and application counts, plus the add-domain
 // form (spec 7.2.2). Applications and the send log arrive in later phases.
 func (s *Server) handleDashboard(w http.ResponseWriter, r *http.Request) {
-	s.renderDashboard(w, r, http.StatusOK, "", "")
+	s.renderDashboard(w, r, http.StatusOK, "", "", "")
 }
 
 // renderDashboard renders the domain list. formErr and formName repopulate the
-// add-domain form after a rejected submission; flash surfaces a one-shot status
-// message keyed by a redirect query flag (never reflected user input).
-func (s *Server) renderDashboard(w http.ResponseWriter, r *http.Request, status int, formErr, formName string) {
+// add-domain form after a rejected submission; importErr surfaces a failed
+// domain import (spec 7.5.B); flash surfaces a one-shot status message keyed by
+// a redirect query flag (never reflected user input).
+func (s *Server) renderDashboard(w http.ResponseWriter, r *http.Request, status int, formErr, formName, importErr string) {
 	domains, err := s.domains.List()
 	if err != nil {
 		logf("panel: dashboard: list domains: %v", err)
@@ -27,12 +28,13 @@ func (s *Server) renderDashboard(w http.ResponseWriter, r *http.Request, status
 		return
 	}
 	s.render(w, status, "dashboard", map[string]any{
-		"Title":    "SelfPost",
-		"User":     currentUser(r),
-		"Domains":  domains,
-		"Error":    formErr,
-		"FormName": formName,
-		"Flash":    dashboardFlash(r),
+		"Title":     "SelfPost",
+		"User":      currentUser(r),
+		"Domains":   domains,
+		"Error":     formErr,
+		"FormName":  formName,
+		"ImportErr": importErr,
+		"Flash":     dashboardFlash(r),
 	})
 }
 
@@ -54,25 +56,25 @@ func dashboardFlash(r *http.Request) string {
 // publish is shown (spec 7.2.3).
 func (s *Server) handleAddDomain(w http.ResponseWriter, r *http.Request) {
 	if err := r.ParseForm(); err != nil {
-		s.renderDashboard(w, r, http.StatusBadRequest, "Invalid form submission.", "")
+		s.renderDashboard(w, r, http.StatusBadRequest, "Invalid form submission.", "", "")
 		return
 	}
 	raw := r.PostFormValue("name")
 	name := normalizeDomain(raw)
 	if err := validateDomain(name); err != nil {
-		s.renderDashboard(w, r, http.StatusBadRequest, err.Error(), raw)
+		s.renderDashboard(w, r, http.StatusBadRequest, err.Error(), raw, "")
 		return
 	}
 
 	d, err := s.domains.Add(name)
 	if err != nil {
 		if errors.Is(err, store.ErrDomainExists) {
-			s.renderDashboard(w, r, http.StatusConflict, "That domain is already configured.", raw)
+			s.renderDashboard(w, r, http.StatusConflict, "That domain is already configured.", raw, "")
 			return
 		}
 		logf("panel: add domain %q: %v", name, err)
 		s.renderDashboard(w, r, http.StatusInternalServerError,
-			"Could not add the domain. Please check the logs and try again.", raw)
+			"Could not add the domain. Please check the logs and try again.", raw, "")
 		return
 	}
 	http.Redirect(w, r, fmt.Sprintf("/domains/%d", d.ID), http.StatusSeeOther)

internal/web/templates/dashboard.html

@@ -53,4 +53,31 @@
   <p class="muted">No domains yet. Add one above to get started.</p>
   {{end}}
 </div>
+
+<div class="card">
+  <h2>Backup &amp; migration</h2>
+  <p class="muted">Download a full backup of all persistent state — the database,
+  every domain's DKIM key and the application credentials. Use it to move the
+  whole server to a new machine: restore it into a container of the
+  <strong>same SelfPost version</strong>, with the same data mount, before first
+  start. TLS certificates and the mail queue are not included.</p>
+  <p class="muted"><strong>The backup file is a secret</strong> (it contains
+  private keys and credentials). Store and transfer it securely and delete it
+  once the restore succeeds.</p>
+  <form class="inline" method="post" action="/backup">
+    <button type="submit">Download full backup</button>
+  </form>
+
+  <h2>Import a domain</h2>
+  <p class="muted">Move a single domain here from another SelfPost instance using
+  a domain export file (from that domain's page). Its DKIM key and application
+  passwords come across, so the published DNS record needs no change. The export
+  file is a secret, like a full backup.</p>
+  {{if .ImportErr}}<p class="error">{{.ImportErr}}</p>{{end}}
+  <form method="post" action="/domains/import" enctype="multipart/form-data">
+    <label for="importfile">Domain export file</label>
+    <input id="importfile" name="file" type="file" accept=".json,application/json" required>
+    <button type="submit">Import domain</button>
+  </form>
+</div>
 {{end}}

internal/web/templates/domain_detail.html

@@ -177,6 +177,19 @@
   be unique across all domains and may contain letters, digits, '.', '-' and '_'.</p>
 </div>
 
+<div class="card">
+  <h2>Export domain</h2>
+  <p class="muted">Download this domain to move it to another SelfPost instance:
+  its DKIM key, selector and every application with its working password. On
+  import the DNS record stays the same, so no DNS change is needed.</p>
+  <p class="muted"><strong>The export file is a secret</strong> — it contains the
+  private DKIM key and application passwords. Transfer it securely and delete it
+  after the import.</p>
+  <form class="inline" method="post" action="/domains/{{.Domain.ID}}/export">
+    <button type="submit">Export domain</button>
+  </form>
+</div>
+
 <div class="card">
   <h2>Danger zone</h2>
   <p class="muted">Deleting this domain also deletes its DKIM key and every

internal/web/web.go

@@ -31,6 +31,12 @@ type Config struct {
 	// monitoring view (spec 7.2.13). It is the same path the log-tailer role
 	// follows in cmd/panel.
 	MailLogPath string
+	// DataDir and DBPath locate the persistent state a full backup archives
+	// (spec 7.5.A); Version is stamped into the backup manifest. They mirror the
+	// panel's own configuration.
+	DataDir string
+	DBPath  string
+	Version string
 }
 
 // Server is the panel HTTP application.
@@ -102,17 +108,22 @@ func (s *Server) Handler() http.Handler {
 	authed := http.NewServeMux()
 	authed.HandleFunc("GET /{$}", s.handleDashboard)
 	authed.HandleFunc("POST /domains", s.handleAddDomain)
+	authed.HandleFunc("POST /domains/import", s.handleImportDomain)
 	authed.HandleFunc("GET /domains/{id}", s.handleDomainDetail)
 	authed.HandleFunc("GET /domains/{id}/delete", s.handleDeleteConfirm)
 	authed.HandleFunc("POST /domains/{id}/delete", s.handleDeleteDomain)
 	authed.HandleFunc("POST /domains/{id}/applications", s.handleAddApplication)
 	authed.HandleFunc("POST /domains/{id}/ratelimit", s.handleDomainRateLimit)
+	authed.HandleFunc("POST /domains/{id}/export", s.handleExportDomain)
 	authed.HandleFunc("POST /applications/{aid}/mode", s.handleUpdateAppMode)
 	authed.HandleFunc("POST /applications/{aid}/password", s.handleRegenPassword)
 	authed.HandleFunc("POST /applications/{aid}/ratelimit", s.handleAppRateLimit)
 	authed.HandleFunc("POST /applications/{aid}/delete", s.handleDeleteApplication)
 	authed.HandleFunc("POST /reload", s.handleReload)
 
+	// Full-server backup download (spec 7.5.A).
+	authed.HandleFunc("POST /backup", s.handleBackup)
+
 	// Monitoring screens (spec 7.2.11-13): each page and its HTMX polling
 	// fragment (spec 7.1 — the /rows and /body endpoints return HTML, not JSON).
 	authed.HandleFunc("GET /sendlog", s.handleSendLog)