Phase 10: deployment (Apache compose + proxy fragments, CI release) + docs

- deploy/docker-compose.yml: pinned-tag ghcr image, hardened (cap_drop ALL +
  minimal cap_add, no-new-privileges, panel bound to 127.0.0.1 only). Apache
  itself runs on the host (spec 10.5), fragment at deploy/apache/.
- Alternative reverse-proxy fragments: nginx (+certbot sidecar), Caddy
  (automatic ACME), Traefik (+acme.json PEM extraction script).
- .github/workflows/release.yml: tag-triggered ghcr.io publish, version piped
  from the git tag into both the binary ldflags and the image tag (spec 10.1).
- Closed a gap from Phase 1: logrotate was installed but never invoked;
  wired up build/logrotate-mail.conf + logrotate-loop.sh + a supervisor
  program (copytruncate, since postlogd holds mail.log open with nothing to
  signal on rotation).
- README rewritten: site requirements checklist, reverse-proxy comparison,
  DNS setup (server- vs domain-level), IP warmup, backup/restore vs domain
  export/import, fixed-tag rationale, machine requirements.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

deploy/.env.example

@@ -0,0 +1,17 @@
+# Copy to .env next to docker-compose.yml and fill in.
+
+# Hostname used both for the panel's TLS vhost and for Postfix's SASL realm
+# (SASL_REALM defaults to this) and myhostname. Must match the certificate
+# your reverse proxy obtains.
+SELFPOST_HOSTNAME=mail.example.com
+
+# Set to true to also enable RFC 6409 submission (587/STARTTLS) alongside the
+# primary 465/smtps listener.
+SUBMISSION_ENABLE=false
+
+# Level-1 backstop rate limit (anvil) — see README "Rate limiting".
+RATE_LIMIT_MESSAGES_PER_IP=100
+RATE_LIMIT_WINDOW_SECONDS=3600
+
+# Days of send-log history kept before the background sweep deletes rows.
+SEND_LOG_RETENTION_DAYS=90

deploy/apache/selfpost-vhost.conf

@@ -0,0 +1,41 @@
+# Example host Apache vhost for the SelfPost panel (spec 10.3, default
+# scenario). Install on the host running Apache — NOT inside the SelfPost
+# container. Requires mod_ssl and mod_proxy/mod_proxy_http enabled
+# (`a2enmod ssl proxy proxy_http`).
+#
+# Certificates: obtain with the Apache certbot plugin against THIS vhost
+# (`certbot --apache -d mail.example.com`). Certbot edits this file in place
+# to add the SSLCertificateFile/SSLCertificateKeyFile directives and a
+# :80 -> :443 redirect vhost, and renews in the background via its own timer.
+# The resulting PEM files land at
+# /etc/letsencrypt/live/mail.example.com/{fullchain,privkey}.pem on the host
+# — bind-mount that directory read-only into the SelfPost container (see
+# ../docker-compose.yml, the `./certs:/etc/postfix/tls:ro` volume) so Postfix
+# can present the very same certificate on 465/587. One certificate, two
+# consumers (spec 10 p.4) — no separate cert just for the panel.
+
+<VirtualHost *:443>
+	ServerName mail.example.com
+
+	# Filled in by `certbot --apache`; shown here for clarity.
+	# SSLEngine on
+	# SSLCertificateFile /etc/letsencrypt/live/mail.example.com/fullchain.pem
+	# SSLCertificateKeyFile /etc/letsencrypt/live/mail.example.com/privkey.pem
+
+	ProxyPreserveHost On
+	ProxyPass "/" "http://127.0.0.1:8080/"
+	ProxyPassReverse "/" "http://127.0.0.1:8080/"
+
+	# The panel is plain HTTP behind the proxy; it never terminates TLS
+	# itself (spec 10 p.2). Cookies are still marked Secure by the panel
+	# (spec 7.6.6) because the browser only ever sees this HTTPS vhost.
+</VirtualHost>
+
+<VirtualHost *:80>
+	ServerName mail.example.com
+	# certbot's http-01 challenge needs this on plain :80; everything else
+	# redirects to HTTPS once certbot adds the RewriteRule/Redirect block.
+	RewriteEngine On
+	RewriteCond %{REQUEST_URI} !^/\.well-known/acme-challenge/
+	RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [R=301,L]
+</VirtualHost>

deploy/caddy/Caddyfile

@@ -0,0 +1,3 @@
+mail.example.com {
+	reverse_proxy selfpost:8080
+}

deploy/caddy/docker-compose.caddy.yml

@@ -0,0 +1,49 @@
+
+# Alternative reverse-proxy: Caddy (spec 10.3) — the simplest option, fully
+# automatic ACME with no separate certbot container. Caddy writes certificates
+# as plain PEM under its own data directory, which this fragment bind-mounts
+# to the host so SelfPost can read the same files.
+#
+# NOTE (spec 10.3 explicitly flags this): Caddy's on-disk cert path includes
+# the ACME CA's name as a path segment, e.g.
+#   <data>/caddy/certificates/acme-v02.api.letsencrypt.org-directory/<hostname>/<hostname>.crt
+# This has been stable across recent Caddy releases but is an internal
+# storage detail, not a documented public API — VERIFY the exact path against
+# the Caddy version you deploy (`docker compose exec caddy find /data/caddy/certificates -name '*.crt'`)
+# before wiring it into the volume mount below.
+#
+# Merge with the base file — run this from the deploy/ directory (Compose
+# resolves every relative path in both files against the directory of the
+# FIRST -f file, i.e. deploy/, which is why paths below are ./caddy/...):
+#
+#   docker compose -f docker-compose.yml -f caddy/docker-compose.caddy.yml up -d
+
+services:
+  selfpost:
+    ports: !override
+      - "465:465"
+      - "587:587"
+    environment:
+      # Caddy names certificate files after the hostname, not
+      # fullchain.pem/privkey.pem like certbot — override the base file's
+      # paths to match.
+      TLS_CERT_FILE: /etc/postfix/tls/<hostname>.crt
+      TLS_KEY_FILE: /etc/postfix/tls/<hostname>.key
+    volumes: !override
+      - ./data:/data
+      # Replace <hostname> with your actual mail/panel hostname, matching
+      # the Caddyfile below and SELFPOST_HOSTNAME.
+      - ./caddy/caddy-data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/<hostname>:/etc/postfix/tls:ro
+
+  caddy:
+    image: caddy:2
+    restart: unless-stopped
+    depends_on:
+      - selfpost
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
+      - ./caddy/caddy-data:/data
+      - ./caddy/caddy-config:/config

deploy/docker-compose.yml

@@ -0,0 +1,80 @@
+
+# SelfPost — default deployment, reverse-proxy = Apache (spec 10, 10.5).
+#
+# This file only runs SelfPost itself. Apache is assumed to already be
+# installed on the HOST (the target audience for this project typically runs
+# Apache there already — spec 10.5) and reverse-proxies HTTPS for the panel;
+# it is not containerised here. See ../apache/selfpost-vhost.conf for a ready
+# vhost fragment, and the "Reverse proxy" section of ../../README.md for the
+# certbot steps that produce the PEM files this compose file mounts.
+#
+# Usage:
+#   1. Copy this file (and .env.example as .env) next to your own ./data and
+#      ./certs directories, or adjust the paths below.
+#   2. Fill in .env (hostname, at least one strong TLS_CERT/KEY path).
+#   3. docker compose up -d
+#
+# The image tag below is FIXED on purpose (spec 10 p.10, 7.5.A): backup
+# restore compares the manifest version against the running binary's version,
+# so ":latest" would make that check meaningless. Bump the tag deliberately
+# when you want to upgrade.
+
+services:
+  selfpost:
+    image: ghcr.io/mixeme/selfpost:1.0.0
+    restart: unless-stopped
+    environment:
+      SELFPOST_HOSTNAME: "${SELFPOST_HOSTNAME:?set the mail/panel hostname, e.g. mail.example.com}"
+      # Path Postfix reads inside the container — matches the certs bind mount
+      # below. Point these at your reverse-proxy's PEM output (spec 10 p.2).
+      TLS_CERT_FILE: /etc/postfix/tls/fullchain.pem
+      TLS_KEY_FILE: /etc/postfix/tls/privkey.pem
+      # Set to true to also publish RFC 6409 submission (587/STARTTLS)
+      # alongside the primary 465/smtps listener (spec 5).
+      SUBMISSION_ENABLE: "${SUBMISSION_ENABLE:-false}"
+      # Level-1 backstop rate limit (anvil, spec 5.5, 7.4); per-domain/app
+      # limits (level 2) are configured later from the panel itself.
+      RATE_LIMIT_MESSAGES_PER_IP: "${RATE_LIMIT_MESSAGES_PER_IP:-100}"
+      RATE_LIMIT_WINDOW_SECONDS: "${RATE_LIMIT_WINDOW_SECONDS:-3600}"
+      # How long the send log keeps rows before the background sweep deletes
+      # them (spec 7.3, 9) — the main driver of /data growth over time.
+      SEND_LOG_RETENTION_DAYS: "${SEND_LOG_RETENTION_DAYS:-90}"
+    volumes:
+      # All persistent state lives under /data (spec 9): SQLite DB, DKIM keys,
+      # sasldb2, sender map, setup token. Back this up (panel button or the
+      # selfpost-backup CLI) before you touch it directly.
+      - ./data:/data
+      # Read-only: SelfPost only ever reads certificates, never manages them
+      # (spec 10 p.2). Point this at wherever your reverse-proxy/certbot
+      # writes PEM files, e.g. /etc/letsencrypt on the host.
+      - ./certs:/etc/postfix/tls:ro
+    ports:
+      # 465 (smtps, primary) and optionally 587 (submission/STARTTLS) are
+      # published directly — mail traffic bypasses Apache entirely, it only
+      # ever proxies the panel's HTTP(S) (spec 10 p.2-3). The panel itself
+      # (8080) is intentionally NOT published here: Apache reaches it over
+      # the host network at 127.0.0.1:8080 (see the vhost fragment), so the
+      # panel is never directly reachable from the internet without TLS.
+      - "465:465"
+      - "587:587"
+      - "127.0.0.1:8080:8080"
+    # Hardening (spec 10 p.6). SelfPost's entrypoint still needs to run as
+    # root very briefly to fix /data ownership and normalise permissions
+    # under the shared `selfpost` group (see build/entrypoint.sh) before
+    # supervisord drops the panel to an unprivileged user — so this cannot be
+    # `user: panel` or a fully read-only rootfs without breaking that startup
+    # self-healing. What IS applied: no privilege escalation past what the
+    # image already grants, and every Linux capability dropped except the
+    # small set Postfix/OpenDKIM genuinely need (binding <1024, chown/setuid
+    # during startup, and DAC overrides for cross-user file access within the
+    # shared group).
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_BIND_SERVICE
+      - CHOWN
+      - SETUID
+      - SETGID
+      - DAC_OVERRIDE

deploy/nginx/docker-compose.nginx.yml

@@ -0,0 +1,55 @@
+
+# Alternative reverse-proxy: nginx (spec 10.3). PEM files land on the host
+# exactly like the Apache+certbot scenario — nginx and certbot are close
+# cousins here, both writing/reading plain PEM under /etc/letsencrypt.
+#
+# This is a FRAGMENT, not a full replacement for ../docker-compose.yml: it
+# adds an nginx + certbot pair and removes the panel's host port publish (nginx
+# takes over 80/443 and proxies to the panel over the compose network
+# instead). Merge it with the base file — run this from the deploy/ directory
+# (Compose resolves every relative path in both files against the directory of
+# the FIRST -f file, i.e. deploy/, which is why paths below are ./nginx/...):
+#
+#   docker compose -f docker-compose.yml -f nginx/docker-compose.nginx.yml up -d
+#
+# First-run certificate issuance (webroot method, before nginx has a cert to
+# serve — run once):
+#   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
+
+services:
+  selfpost:
+    ports: !override
+      - "465:465"
+      - "587:587"
+      # No host publish for 8080 here: nginx reaches it over the compose
+      # network at selfpost:8080 instead (see nginx.conf.example).
+    volumes: !override
+      - ./data:/data
+      # Same host directory certbot below writes into — plain bind mount,
+      # no named volume, so the PEM files are as directly inspectable as in
+      # the Apache scenario (spec 10.3).
+      - ./nginx/certbot-etc/live/mail.example.com:/etc/postfix/tls:ro
+
+  nginx:
+    image: nginx:1.27
+    restart: unless-stopped
+    depends_on:
+      - selfpost
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx/nginx.conf.example:/etc/nginx/conf.d/selfpost.conf:ro
+      - ./nginx/certbot-etc:/etc/letsencrypt:ro
+      - ./nginx/certbot-www:/var/www/certbot:ro
+
+  certbot:
+    image: certbot/certbot:latest
+    volumes:
+      - ./nginx/certbot-etc:/etc/letsencrypt
+      - ./nginx/certbot-www:/var/www/certbot
+    # Renewal twice a day is certbot's own recommended cadence; it no-ops
+    # until a certificate is within its renewal window.
+    entrypoint: sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done'

deploy/nginx/nginx.conf.example

@@ -0,0 +1,32 @@
+# nginx vhost for the SelfPost panel (spec 10.3). Proxies HTTPS to the panel
+# over the compose network; mail (465/587) is published directly by the
+# selfpost container and never touches nginx.
+
+server {
+	listen 80;
+	server_name mail.example.com;
+
+	location /.well-known/acme-challenge/ {
+		root /var/www/certbot;
+	}
+
+	location / {
+		return 301 https://$host$request_uri;
+	}
+}
+
+server {
+	listen 443 ssl;
+	http2 on;
+	server_name mail.example.com;
+
+	ssl_certificate     /etc/letsencrypt/live/mail.example.com/fullchain.pem;
+	ssl_certificate_key /etc/letsencrypt/live/mail.example.com/privkey.pem;
+
+	location / {
+		proxy_pass http://selfpost:8080;
+		proxy_set_header Host $host;
+		proxy_set_header X-Forwarded-Proto $scheme;
+		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+	}
+}

deploy/traefik/docker-compose.traefik.yml

@@ -0,0 +1,52 @@
+
+# Alternative reverse-proxy: Traefik (spec 10.3). Traefik does NOT write plain
+# PEM files — everything (cert + key) lives bundled inside acme.json. SelfPost
+# needs separate PEM files for Postfix, so an extraction step is required; see
+# extract-cert.sh in this directory and the cron/systemd-timer note below.
+#
+# Merge with the base file — run this from the deploy/ directory (Compose
+# resolves every relative path in both files against the directory of the
+# FIRST -f file, i.e. deploy/, which is why paths below are ./traefik/...):
+#
+#   docker compose -f docker-compose.yml -f traefik/docker-compose.traefik.yml up -d
+
+services:
+  selfpost:
+    ports: !override
+      - "465:465"
+      - "587:587"
+    volumes: !override
+      - ./data:/data
+      # Populated by extract-cert.sh from traefik's acme.json — see below.
+      - ./traefik/extracted-certs:/etc/postfix/tls:ro
+    labels:
+      # Traefik only proxies the panel; it never sees the mail ports.
+      # These live on the selfpost service (not traefik's) because the
+      # docker provider reads routing labels off the container being routed
+      # to, not off traefik itself.
+      - traefik.enable=true
+      - traefik.http.routers.selfpost.rule=Host(`mail.example.com`)
+      - traefik.http.routers.selfpost.entrypoints=websecure
+      - traefik.http.routers.selfpost.tls.certresolver=le
+      - traefik.http.services.selfpost.loadbalancer.server.port=8080
+
+  traefik:
+    image: traefik:v3.1
+    restart: unless-stopped
+    depends_on:
+      - selfpost
+    command:
+      - --providers.docker=true
+      - --providers.docker.exposedbydefault=false
+      - --entrypoints.web.address=:80
+      - --entrypoints.websecure.address=:443
+      - --entrypoints.web.http.redirections.entrypoint.to=websecure
+      - --certificatesresolvers.le.acme.email=you@example.com
+      - --certificatesresolvers.le.acme.storage=/letsencrypt/acme.json
+      - --certificatesresolvers.le.acme.httpchallenge.entrypoint=web
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ./traefik/letsencrypt:/letsencrypt

deploy/traefik/extract-cert.sh

@@ -0,0 +1,28 @@
+#!/bin/sh
+# Extracts a PEM cert/key pair for one domain out of Traefik's acme.json
+# (spec 10.3: "Traefik — сертификаты в acme.json, потребуется шаг извлечения
+# PEM"). Run this on the host, after Traefik has issued or renewed the
+# certificate, and again on a schedule (cron/systemd timer) since acme.json
+# is not itself watched by SelfPost/Postfix.
+#
+# Requires jq. Usage: ./extract-cert.sh <acme.json path> <domain> <output dir>
+set -eu
+
+ACME_JSON="${1:?path to acme.json}"
+DOMAIN="${2:?domain name, e.g. mail.example.com}"
+OUT_DIR="${3:?output directory, e.g. ./extracted-certs}"
+
+mkdir -p "$OUT_DIR"
+
+jq -r --arg domain "$DOMAIN" '
+  .le.Certificates[]
+  | select(.domain.main == $domain)
+  | .certificate' "$ACME_JSON" | base64 -d > "$OUT_DIR/fullchain.pem"
+
+jq -r --arg domain "$DOMAIN" '
+  .le.Certificates[]
+  | select(.domain.main == $domain)
+  | .key' "$ACME_JSON" | base64 -d > "$OUT_DIR/privkey.pem"
+
+chmod 0640 "$OUT_DIR/fullchain.pem" "$OUT_DIR/privkey.pem"
+echo "extracted $DOMAIN to $OUT_DIR/{fullchain,privkey}.pem"