Backups & restore

All state lives in one SQLite file, which makes backup simple: a daily compacted snapshot is gzipped and uploaded to any S3-compatible bucket (Cloudflare R2, S3, MinIO, …) as clacks-YYYYMMDD-HHMMSS.db.gz.

Enable

environment:
  CLACKS_BACKUP_ENABLED: "true"
  CLACKS_BACKUP_ACCOUNT_ID: "your-cloudflare-account-id"   # builds the R2 endpoint
  # CLACKS_BACKUP_ENDPOINT: "https://s3.example.com"       # or any S3 endpoint
  CLACKS_BACKUP_BUCKET: "my-clacks-backups"
  CLACKS_BACKUP_ACCESS_KEY_ID: "…"
  CLACKS_BACKUP_SECRET_ACCESS_KEY: "…"
  CLACKS_BACKUP_HOUR: "3"          # local hour of the daily run

Retention is the bucket's job — set a lifecycle rule (e.g. expire after 30 days). Clacks never deletes backups.

Run one now, or manage from the web UI (Admin → Backups):

docker compose exec clacks clacks backup
docker compose exec clacks clacks backup list

What's included

• The database — every user, message, alias, certificate, and setting.
• Rspamd's learning (if you set CLACKS_RSPAMD_REDIS_HOST) — the trained Bayes/neural data is dumped from Redis and uploaded alongside as clacks-<timestamp>.rspamd.gz, so a rebuilt server keeps its spam training.

Disaster recovery: restore on boot

On a fresh host, set one extra variable pointing at a backup object (or an https:// URL):

environment:
  CLACKS_RESTORE_FROM: "clacks-20260707-030000.db.gz"

On boot, clacks downloads it, validates it, swaps it in as the live database, and (when present and Redis is configured) restores the paired Rspamd training. Then:

1. Remove CLACKS_RESTORE_FROM and restart — otherwise the next restart overwrites your now-live data with the old backup again.
2. Keep CLACKS_SECRET the same as the old host so stored IMAP-import credentials survive.

Manual restore is also available:

docker compose exec clacks clacks backup restore clacks-20260707-030000.db.gz --output /data/restored.db

Test it once

Do a throwaway restore before you need it: point a scratch container at a real backup, confirm it boots and your mail is there.