davekilleen/dex/backup-setup

Backup Setup

Set up (or change) automatic backups of the whole vault: notes, projects, people, tasks, settings, and the vault's own version history. Runs on a schedule in the background, keeps a sensible ladder of older copies, and tells you loudly if it ever stops working.

What a backup contains

Every run writes a set of three files, stamped with the date and time:

Secrets are deliberately left out: the .env file holding AI keys, generated tool configuration that can reference credentials, saved sign-in tokens (*token.json), the System/credentials folder, any .key or .pem file, virtual environments, and caches. Never store those in a synced folder. Keys live in the system keychain or get re-entered on restore. See docs/backup-restore.md for what a full rebuild needs beyond these files.

Step 1: Where should backups go?

Ask which destination suits them, in plain terms:

1. A synced folder (default, simplest): OneDrive, iCloud Drive, Dropbox, Google Drive, or a plugged-in external disk. Anything that looks like a folder on their Mac. The file-sync app carries copies off the machine.
2. A cloud storage provider directly: Amazon S3, Backblaze B2, Google Drive proper, and around seventy others, using a tool called rclone. Choose this when they want backups genuinely off their machine rather than mirrored by a sync app, or their vault is large enough that a sync folder is awkward.

For option 1 ask for the folder path. Offer to detect likely candidates:

ls -d ~/Library/CloudStorage/* ~/Dropbox ~/Google\ Drive 2>/dev/null

For option 2, check whether rclone is present and configured:

rclone listremotes

If they choose rclone, use a named remote they created with rclone config (for example b2:dex-backups). Never put an inline connection string carrying a key or secret into backup.remote: it would be written to the local run record and archived inside the backup itself.

If rclone is missing, say so plainly and give them the choice: install it (brew install rclone, then rclone config to add their provider) or start with a synced folder now and switch later. Do not attempt to configure their cloud credentials for them; rclone's own setup handles that interactively and safely.

Step 2: How many copies to keep?

Explain the default in one line: 7 daily, 4 weekly, 3 monthly. Recent copies for accidents, older copies for problems noticed late (a bad edit that spread quietly, a file corrupted weeks ago). Roughly fourteen sets, which for a typical vault is a couple of gigabytes.

Accept a different ladder if they want one. The newest set is never deleted, whatever the ladder says.

Step 3: Save the settings

Write to System/integrations/config.yaml under backup::

backup:
  enabled: true
  backend: folder          # folder | rclone
  destination: /path/to/folder    # folder backend
  remote: ""                      # rclone backend, e.g. "b2:dex-backups"
  retention:
    daily: 7
    weekly: 4
    monthly: 3

Step 4: Schedule it

Install the background job (daily, 12:30 by default; ask if they'd prefer another time, and pick a time their machine is usually awake):

python3 core/backup/install_backup_job.py --hour 12 --minute 30

On macOS this schedules the job so missed runs fire when the machine wakes. On other platforms the installer does not pretend: it prints the exact line to schedule the same command with the platform's own scheduler, and installs nothing.

Step 5: Prove it works

Do not tell them backups are set up until one has actually run. Run one now:

python3 core/backup/backup_vault.py

Then show them the real result from System/.dex/backup-last-run.json: the set name, size, and destination. If it failed, show the recorded error and fix the cause before declaring success.

Finish by telling them three things: where backups are going, how to get one on demand (/backup-now), and that /backup-restore in test mode proves a restore works without touching anything.

If backups stop working

Opening Dex warns when the newest successful backup is more than two days old, or the last run failed — the same ⏰ notice used for meeting sync. Ordinary /dex-doctor (no extra scan) reads the last-run record and says what went wrong. If they ask why a warning appeared, read System/.dex/backup-last-run.json and report the recorded error verbatim rather than guessing. A single file that could not be read is named in that record and does not block the rest of the backup.