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/.env.prod.example

@@ -0,0 +1,111 @@
+# ============================================================================
+#  Webmail production configuration.
+#
+#  Copy to docker/.env.prod, fill in the three REQUIRED values, keep it safe:
+#      cp docker/.env.prod.example docker/.env.prod && chmod 600 docker/.env.prod
+#
+#  THIS FILE IS A BACKUP ARTEFACT. MASTER_KEY is not stored anywhere else: lose
+#  it and every saved mail-account password becomes permanently undecryptable,
+#  even from a perfect database backup. Keep a copy in a password manager.
+# ============================================================================
+
+# --- REQUIRED ---------------------------------------------------------------
+
+# Where all persistent data lives on the host. Use a real shared folder your NAS
+# backup tool can see — not a Docker named volume.
+#   Synology: /volume1/docker/webmail/data
+#   QNAP:     /share/Container/webmail/data
+DATA_ROOT=/volume1/docker/webmail/data
+
+# 32 random bytes, base64. Generate ONCE, then never change it:
+#   openssl rand -base64 32
+MASTER_KEY=
+
+# Database password. Generate once:
+#   openssl rand -base64 24 | tr -d '/+=' | cut -c1-24
+POSTGRES_PASSWORD=
+
+# --- Identity ---------------------------------------------------------------
+# The domain your user handles are minted under (user@APP_DOMAIN) and the issuer
+# shown in 2FA authenticator apps. It does NOT have to be publicly resolvable.
+APP_DOMAIN=mail.home.lan
+
+# --- Network ----------------------------------------------------------------
+# The single published port. Avoid 5000/5001 (Synology DSM) and 8080 (QNAP QTS).
+WEB_PORT=8088
+# Bind to one NAS interface instead of every network, e.g. WEB_BIND=192.168.1.185
+WEB_BIND=0.0.0.0
+
+TZ=Europe/Warsaw
+
+# --- Search -----------------------------------------------------------------
+# pg   = Postgres full-text. No extra container, no extra RAM. Default.
+# meili = Meilisearch: typo tolerance, better ranking, faster on large mailboxes.
+#         Costs a container and ~0.7-1 GB RAM. Start it with:
+#             ./deploy/webmail.sh up --meili
+#         and after switching an existing install, rebuild the index:
+#             ./deploy/webmail.sh reindex
+SEARCH_BACKEND=pg
+# Required if SEARCH_BACKEND=meili — generate with: openssl rand -base64 32
+MEILI_MASTER_KEY=
+
+# --- Images -----------------------------------------------------------------
+# `local` = built on this host from the repo. To deploy prebuilt images from
+# your Gitea registry instead, set both of these (see deploy/build-push.sh):
+#   REGISTRY_PREFIX=192.168.1.185:8418/claude/webmail
+#   IMAGE_TAG=v1.0.0
+REGISTRY_PREFIX=webmail
+IMAGE_TAG=local
+
+# --- Application ------------------------------------------------------------
+LOG_LEVEL=INFO
+UNDO_SECONDS=10
+SESSION_TTL_DAYS=30
+MAX_ATTACHMENT_MB=25
+# Auto-purge Trash/Spam older than N days (0 disables).
+TRASH_RETENTION_DAYS=30
+# Server-side sender avatars (Gravatar + favicon), fetched by the server so
+# senders never see your IP. Set false to make zero outbound web requests.
+SENDER_AVATARS_ENABLED=true
+
+GOOGLE_OAUTH_ENABLED=false
+OAUTH_GOOGLE_CLIENT_ID=
+OAUTH_GOOGLE_CLIENT_SECRET=
+OAUTH_MS_CLIENT_ID=
+OAUTH_MS_CLIENT_SECRET=
+
+# Plugins whose schema is migrated on every start. Remove one to stop shipping
+# its tables; `hello` is the SDK demo and is intentionally not listed.
+ENABLED_PLUGINS=calendar contacts labels filters
+
+# --- Backups ----------------------------------------------------------------
+BACKUP_AT=03:30
+BACKUP_KEEP_DAYS=14
+
+# --- Sizing (defaults suit a personal install on a shared NAS) --------------
+# Peak worker RAM is roughly PARSE_CONCURRENCY x STREAM_PARSE_MB plus overhead.
+INTERACTIVE_CONCURRENCY=8
+BULK_CONCURRENCY=1
+PARSE_CONCURRENCY=2
+STREAM_PARSE_MB=8
+PER_HOST_CONN_CAP=10
+HOT_BUDGET_PER_WORKER=50
+
+# Container caps. Total without Meilisearch: ~2.2 GB of *limits*; real steady
+# usage for one or two mail accounts is around 700 MB-1 GB.
+PG_MEM_LIMIT=768m
+PG_SHARED_BUFFERS=256MB
+PG_MAX_CONNECTIONS=100
+PG_WORK_MEM=8MB
+PG_MAINTENANCE_WORK_MEM=128MB
+PG_EFFECTIVE_CACHE_SIZE=768MB
+REDIS_MEM_LIMIT=160m
+REDIS_MAXMEMORY=96mb
+API_MEM_LIMIT=512m
+API_CPUS=1.0
+WORKER_SYNC_MEM_LIMIT=512m
+WORKER_JOBS_MEM_LIMIT=640m
+WORKER_CPUS=1.5
+WEB_MEM_LIMIT=96m
+BACKUP_MEM_LIMIT=256m
+MEILI_MEM_LIMIT=1g