Deploy: production Docker stack for a single host (Synology/QNAP NAS)

Everything needed to run the app on an Intel NAS that is also doing other
jobs: one published port, no host networking, memory/CPU caps and log
rotation on every container, and all state in bind mounts under DATA_ROOT
so mail survives image updates, project deletion in the NAS UI, and full
reinstalls — and so Hyper Backup/HBS3 can actually see it.

- docker/Dockerfile.backend: multi-stage, non-root (uid 10001), tini for
  the <10s graceful lease release. Installs the four plugins as entry-point
  distributions. One image, several roles via docker/entrypoint.sh
  (api | worker-sync | worker-jobs | migrate | reindex | plugins).
- docker/Dockerfile.frontend + nginx.conf: SPA + /api reverse proxy with
  the WebSocket upgrade for /api/ws, and X-Forwarded-Proto preserved so
  the API still emits __Host-/Secure cookies when TLS is terminated by
  the NAS reverse proxy (identity/cookies.py keys off request scheme).
- docker/docker-compose.prod.yml: project name webmail-prod, NOT webmail —
  docker-compose.yml (dev services) owns that name, and two compose files
  sharing one project name fight over each other's containers.
  Meilisearch is an opt-in profile; SEARCH_BACKEND=pg is the default so a
  small NAS pays nothing for search.
- migrate runs as a one-shot (core Alembic head + every plugin branch)
  that everything else waits on, so a bad migration can never leave new
  code running against an old schema.
- docker/backup.sh: nightly pg_dump verified with `pg_restore --list`
  before it counts as a backup, with retention and a baseline on first
  start.
- deploy/webmail.sh: init/doctor/up/down/status/logs/update/rollback/
  backup/restore/reindex/psql/shell. `update` is backup -> images ->
  migrate -> roll workers, api, web -> health-gate, with automatic
  rollback to the previous version if the gate fails. `doctor` refuses to
  be quiet when DATA_ROOT is on NFS/SMB (silent Postgres corruption).
- deploy/build-push.sh: build images off-NAS (the frontend build wants
  ~2GB RAM) and push to Gitea, or --save a tar to carry over.
- scripts/reindex_search.py: rebuild the search index from Postgres alone.
  Every SearchDoc field is already stored, so the index is derived data
  that never needs backing up — this closes the only real objection to
  running Meilisearch on a box whose volumes may be wiped.
- pyproject: package-data for accounts/presets.yaml and the shared plugin
  Alembic env. Without it a non-editable install (i.e. any image) silently
  ships a package that fails at runtime.
- GET /api/version, used by the deploy health gate.

Verified end to end on a real stack: fresh install, all services healthy,
core + 4 plugin migration branches applied, login/SPA/plugin bundles
through nginx, WS upgrade returning 101, __Host- cookies under a
simulated TLS proxy, backup -> restore round-trip preserving user and
plugin schema, failed-update auto-rollback (both a bad migration and a
boot-crashing API), and Meilisearch profile serving a live query.
ruff + mypy --strict clean, 363/363 backend tests pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nux3LCu4zP9nih4BRhPyHw

docker/backup.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# Nightly logical backup of the webmail database.
+#
+# Runs as a long-lived sidecar: sleeps until BACKUP_AT, dumps, verifies, prunes,
+# repeats. `docker compose run --rm backup once` takes a single backup now (this
+# is what `deploy/webmail.sh backup` does, e.g. immediately before an update).
+#
+# Why logical dumps and not just a NAS snapshot: a btrfs/Hyper Backup snapshot of
+# a *running* Postgres data directory is crash-consistent, which usually replays
+# fine but is not guaranteed and cannot be restored into a different Postgres
+# version. A pg_dump is version-portable and verifiable. Keep both.
+set -euo pipefail
+
+BACKUP_DIR="${BACKUP_DIR:-/backups}"
+BACKUP_AT="${BACKUP_AT:-03:30}"
+BACKUP_KEEP_DAYS="${BACKUP_KEEP_DAYS:-14}"
+DB="${PGDATABASE:-webmail}"
+
+log() { echo "[backup $(date -Is)] $*"; }
+
+take_backup() {
+    local stamp out globals
+    stamp="$(date +%Y%m%d-%H%M%S)"
+    out="${BACKUP_DIR}/${DB}-${stamp}.dump"
+    globals="${BACKUP_DIR}/globals-${stamp}.sql"
+
+    log "dumping ${DB} -> $(basename "$out")"
+    # -Fc: compressed custom format, restorable selectively with pg_restore.
+    if ! pg_dump --format=custom --compress=6 --file="${out}.partial" "$DB"; then
+        log "ERROR: pg_dump failed; leaving no partial file"
+        rm -f "${out}.partial"
+        return 1
+    fi
+
+    # Verify the archive is readable before it counts as a backup.
+    if ! pg_restore --list "${out}.partial" >/dev/null 2>&1; then
+        log "ERROR: dump failed verification (pg_restore --list); discarding"
+        rm -f "${out}.partial"
+        return 1
+    fi
+
+    mv "${out}.partial" "$out"
+    chmod 600 "$out"
+
+    # Roles/passwords live outside the database; tiny, and makes a restore onto a
+    # bare Postgres one step shorter.
+    pg_dumpall --globals-only --file="$globals" 2>/dev/null || true
+    [ -f "$globals" ] && chmod 600 "$globals"
+
+    ln -sfn "$(basename "$out")" "${BACKUP_DIR}/latest.dump"
+    log "ok: $(du -h "$out" | cut -f1) $(basename "$out")"
+
+    log "pruning dumps older than ${BACKUP_KEEP_DAYS} days"
+    find "$BACKUP_DIR" -maxdepth 1 -name "${DB}-*.dump" -mtime "+${BACKUP_KEEP_DAYS}" -print -delete || true
+    find "$BACKUP_DIR" -maxdepth 1 -name "globals-*.sql" -mtime "+${BACKUP_KEEP_DAYS}" -print -delete || true
+}
+
+seconds_until() {
+    local target now next
+    target="$1"
+    now=$(date +%s)
+    next=$(date -d "today ${target}" +%s 2>/dev/null || echo 0)
+    if [ "$next" -le "$now" ]; then
+        next=$(date -d "tomorrow ${target}" +%s)
+    fi
+    echo $(( next - now ))
+}
+
+if [ "${1:-}" = "once" ]; then
+    take_backup
+    exit $?
+fi
+
+log "backup sidecar started; schedule ${BACKUP_AT} daily, retention ${BACKUP_KEEP_DAYS} days"
+
+# Baseline on first start: if there is no dump from the last 24 h, take one now
+# rather than leaving a fresh install unprotected until the first scheduled run.
+if ! find "$BACKUP_DIR" -maxdepth 1 -name "${DB}-*.dump" -mtime -1 | grep -q .; then
+    log "no recent dump found; taking a baseline backup"
+    take_backup || log "baseline backup failed; will retry on schedule"
+fi
+
+while true; do
+    wait_s="$(seconds_until "$BACKUP_AT")"
+    log "next backup in ${wait_s}s (at ${BACKUP_AT})"
+    sleep "$wait_s"
+    take_backup || log "scheduled backup failed; continuing"
+done