Persist Postfix queue and ship self-contained full backups.
Move the mail queue under /data so recreate no longer drops deferred mail, and archive data/, compose, .env, and certs/ together for restore on a fresh host. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
+17
-10
@@ -291,23 +291,27 @@ single-connection trade-off that follows from it.
|
||||
| `opendkim/` | DKIM keys + tables |
|
||||
| `sasl/sasldb2` | Application SASL credentials |
|
||||
| `postfix/sender_login_maps` | Login → From binding |
|
||||
| `postfix/queue/` | Postfix transit mail (deferred/active); survives container recreate |
|
||||
| `log/mail.log` | Postfix delivery log + rotated copies (excluded from backups) |
|
||||
| `manifest.json` | Backup version stamp (consumed on restore) |
|
||||
|
||||
Not in `/data`: TLS certificates (reverse-proxy mount), Postfix queue
|
||||
(transit mail not migrated by design).
|
||||
Not in `/data`: TLS certificates for the panel (reverse-proxy mount) — though
|
||||
full backups also archive the operator's `./certs` PEM files when present.
|
||||
|
||||
**Rotation:** send-log retention `SEND_LOG_RETENTION_DAYS` (default 90);
|
||||
`mail.log` via logrotate (14 rotated files, check every 6h, rename +
|
||||
`postfix reload` in `postrotate` — see § Log tailer above).
|
||||
|
||||
**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. 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).
|
||||
**Restore:** panel button or `selfpost-backup` CLI — self-contained archive:
|
||||
`data/` (SQLite snapshot + tree minus `log/`, the setup token and any `tls/`
|
||||
under `/data`), `docker-compose.yml`, `.env`, and `certs/` when present;
|
||||
version check on restore. Requires the project directory mounted read-only at
|
||||
`SELFPOST_DEPLOY_ROOT` (`/selfpost-deploy` in the default compose file). 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` alone remains possible for state-only copies (see guide).
|
||||
|
||||
**Optional encryption** of the two secret-bearing downloads
|
||||
([internal/secretfile](../internal/secretfile/secretfile.go)): password →
|
||||
@@ -350,7 +354,10 @@ unsupported rather than as a missing doc:
|
||||
`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).
|
||||
desyncs the map Postfix reads from the file the panel maintains),
|
||||
`POSTFIX_QUEUE_DIR` (`/data/postfix/queue` — set in `build/postfix-config.sh`),
|
||||
`SELFPOST_DEPLOY_ROOT` (`/selfpost-deploy` — operator project directory for
|
||||
full backups; mount `.:/selfpost-deploy:ro` in compose).
|
||||
- **Milter and Postfix startup:** `MILTER_CONNECT_TIMEOUT` (`15s`),
|
||||
`MILTER_COMMAND_TIMEOUT` (`15s`), `MILTER_CONTENT_TIMEOUT` (`30s`),
|
||||
`MILTER_WAIT_TIMEOUT` (`30` seconds).
|
||||
|
||||
@@ -14,7 +14,7 @@
|
||||
<div class="pair">
|
||||
<div class="card">
|
||||
<h2>Full backup</h2>
|
||||
<p class="muted">Download a full backup of all persistent state — the database, every domain’s DKIM key and the application credentials. Restore 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">Download a self-contained backup — <code>data/</code> (database, DKIM keys, credentials, Postfix queue), <code>docker-compose.yml</code>, <code>.env</code>, and <code>certs/</code>. Extract into an empty project directory on a new machine, adjust hostname if needed, and start the <strong>same SelfPost version</strong> before first boot. The reverse-proxy vhost is not included.</p>
|
||||
<p class="muted"><strong>The backup file is a secret.</strong> Encrypting it is the simplest way to store it: the download is then a <code>.spbk</code> that only the password opens.</p>
|
||||
<div class="encrypt">
|
||||
<label class="check"><input type="checkbox" checked> <span>Encrypt with a password</span></label>
|
||||
|
||||
+43
-34
@@ -417,25 +417,31 @@ journal-milter (level 2) is down. There is no per-IP bypass.
|
||||
|
||||
### Full backup and restore
|
||||
|
||||
**Full backup** (whole `/data` except `log/`: SQLite, all domains' DKIM keys,
|
||||
all applications' SASL credentials, `manifest.json` with the version that
|
||||
created it): panel button (*Backup* → *Full backup*), or from the host:
|
||||
**Full backup** is a self-contained project archive: `data/` (SQLite, all
|
||||
domains' DKIM keys, all applications' SASL credentials, the Postfix queue,
|
||||
`manifest.json` with the version that created it), plus `docker-compose.yml`,
|
||||
`.env`, and `certs/` from the operator directory next to `./data`. Delivery
|
||||
logs under `data/log/` are excluded. The base compose file mounts the project
|
||||
directory read-only at `/selfpost-deploy` so the panel and CLI can read those
|
||||
deploy files — without that mount, *Full backup* refuses with an error.
|
||||
|
||||
Take a backup from the panel (*Backup* → *Full backup*) or from the 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. 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
|
||||
**Restore** means unpacking that archive into an **empty project directory**
|
||||
(not into `./data` alone) 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, `data/manifest.json`
|
||||
from the archive is **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)).
|
||||
|
||||
@@ -446,16 +452,16 @@ back after a bad change):
|
||||
# 1. Stop the instance being replaced
|
||||
docker compose down
|
||||
|
||||
# 2. Move the current /data aside rather than deleting it, start from empty
|
||||
mv ./data ./data.before-restore
|
||||
mkdir ./data
|
||||
# 2. Move the current project aside rather than deleting it
|
||||
mv . ../selfpost.before-restore
|
||||
mkdir selfpost && cd selfpost
|
||||
|
||||
# 3. Unpack the backup into the fresh directory
|
||||
tar xzf selfpost-backup.tar.gz -C ./data
|
||||
tar xzf ../selfpost-backup.tar.gz
|
||||
|
||||
# 4. docker-compose.yml must already pin the exact tag the backup was made
|
||||
# with — check the archive's manifest if unsure:
|
||||
tar xzf selfpost-backup.tar.gz -O manifest.json
|
||||
# 4. docker-compose.yml in the archive must pin the exact tag the backup was
|
||||
# made with — check if unsure:
|
||||
tar xzf ../selfpost-backup.tar.gz -O data/manifest.json
|
||||
|
||||
# 5. Start it and watch the boot
|
||||
docker compose up -d
|
||||
@@ -473,28 +479,31 @@ 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.
|
||||
**Moving to a different host** is the same flow: create an empty project
|
||||
directory, unpack the backup there, edit `.env` (and `docker-compose.yml` if
|
||||
needed) for the new hostname or proxy, then `docker compose up -d`. The archive
|
||||
carries `certs/` from the old host — re-issue certificates when the hostname or
|
||||
IP changes. Set up the reverse-proxy vhost separately (not in the backup).
|
||||
|
||||
**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:
|
||||
(step 5, but on an empty project you have not 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
|
||||
Stop it, wipe the project directory 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.
|
||||
|
||||
**Archives from older SelfPost versions** (flat layout: `manifest.json` and
|
||||
`selfpost.db` at the archive root, no `data/` prefix, no deploy files) restore
|
||||
with the previous procedure: `tar xzf backup.tar.gz -C ./data` into a project
|
||||
that already has `docker-compose.yml` and `.env`.
|
||||
|
||||
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
|
||||
@@ -520,9 +529,9 @@ 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
|
||||
admin password hash (full backup), TLS private keys and `.env` (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
|
||||
|
||||
+5
-4
@@ -86,10 +86,11 @@ The panel is exposed to the internet — the items below are **not optional**.
|
||||
|
||||
### Backup and domain export
|
||||
|
||||
- Both files are secrets: a full backup carries DKIM keys, `sasldb2`, and the
|
||||
administrator's password hash; a domain export carries the DKIM key and
|
||||
**working** application passwords in the clear (otherwise a transfer without
|
||||
recreating credentials would be impossible).
|
||||
- Both files are secrets: a full backup carries DKIM keys, `sasldb2`, the
|
||||
administrator's password hash, `docker-compose.yml`, `.env`, and the TLS
|
||||
private key from `certs/` when present; a domain export carries the DKIM key
|
||||
and **working** application passwords in the clear (otherwise a transfer
|
||||
without recreating credentials would be impossible).
|
||||
- Both downloads can be encrypted with a password (a checkbox on the form):
|
||||
scrypt (N=2¹⁵, r=8, p=1) → AES-256-GCM, streamed in 64 KiB chunks, each
|
||||
authenticated with the header, the chunk number, and an end-of-stream flag —
|
||||
|
||||
Reference in New Issue
Block a user