setup-backup

Backups to Cloudflare R2

Goal: one private bucket that holds the lodge's nightly backups, each one a single woltspace-backup-<tag>.tar.gz.age encrypted to the owner's age key, and a read-only token that can bring the lodge back on another machine. The full reference is docs/backup.md in the woltspace repo; this skill is the guided path through it.

Rules

• The owner types every secret, never you. Tokens and the age private key are entered by the owner in a normal terminal on their own computer, never in a wolt session (not even with !): anything typed or printed in a session lands in its transcript. Never ask for a key in chat, Telegram or Slack, and never cat, echo or log a secret file. When you check one, mask the values.
• No personal data in the bucket's paths or anything public. Use placeholders: <bucket>, <lodge-id>, <account-id>.
• Every step that costs money, creates a token or changes the owner's Cloudflare account is done by the owner. You guide and verify.
• The age private key never lives on the lodge. The lodge only needs the public age1... key. Whoever has the private key can read every backup; whoever loses it can read none.

The steps (give the owner one at a time)

If the lodge has a site, a one-step-at-a-time page with copy buttons works better than a long chat message.

1. Bucket. Cloudflare dashboard → Storage & databases → R2 → Create bucket. Pick a name (e.g. lodge-backups); default options.
2. Lock rule (snapshots can't be deleted or overwritten, even by a compromised lodge). Bucket → Settings → Bucket lock rules → Add rule: name keep-30d, prefix lodges/<lodge-id>/snapshots/ — exactly this, with the trailing slash. Nothing broader, or the daily latest.json rewrite is blocked. Retention 30 days or more.
3. Lifecycle rule (the bucket doesn't grow forever). Same Settings tab → Object lifecycle rules: prefix lodges/<lodge-id>/snapshots/, delete some time after the lock ends (e.g. 60 days after upload).
4. Two API tokens. R2 Overview → Manage API tokens → Create Account API token:
   • lodge-backup: Object Read & Write, Apply to specific buckets only → this bucket. Goes on the lodge (step 5). R2 has no write-only scope; the lock rule is what makes it effectively append-only.
   • restore: Object Read only, same bucket. Only in the owner's password manager, never on the lodge. The secret is shown once. The S3 endpoint is https://<account-id>.r2.cloudflarestorage.com.
5. rclone config, typed by the owner in their own terminal: nano ~/.config/rclone/rclone.conf, then

   [r2]
   type = s3
   provider = Cloudflare
   access_key_id = <from lodge-backup>
   secret_access_key = <from lodge-backup>
   endpoint = https://<account-id>.r2.cloudflarestorage.com
   acl = private
   no_check_bucket = true
   

   and chmod 600 ~/.config/rclone/rclone.conf.
6. The age key, in the owner's own terminal, on a machine of theirs: age-keygen -o /tmp/lodge-age.txt. The file has 3 lines; the private key is the line starting AGE-SECRET-KEY-1. The owner saves the whole file in their password manager, then rm /tmp/lodge-age.txt, and sends you only the age1... public key (safe to share). That public key is WOLTSPACE_BACKUP_AGE_RECIPIENT, and age must be on the lodge's PATH. With it set, woltspace backup streams the whole archive through age, .env files and bot tokens included (OAuth files never), and nothing unencrypted is written. A recipient set without age fails the backup.
7. The nightly upload. The upload script and the crontab line (or systemd timer) are in docs/backup.md, "The daily upload". The script refuses to run without WOLTSPACE_BACKUP_AGE_RECIPIENT and refuses to upload anything that is not a .tar.gz.age. latest.json carries only the tag, the sha256 of the .age file, the version and the time. Turning it on for the live lodge needs the owner's go.