Backup and restore

What you would lose

Data	Rebuildable?
Watch definitions	Yes — from YAML files, if you keep them
Run state (seen content, notified events, ledger, pending deliveries)	No
Run history	No
Trust rules	Only by hand
Stored API keys	Only by re-adding them
Accounts	Only by recreating them

Losing run state is not neutral

Run state is what stops Watcher repeating itself. Restore an instance without it and the next run treats everything as new: expect a burst of alerts for events you were told about weeks ago.

Free tiers usually do not back up

Most free database tiers provide no automated backups. If that is your setup, backups are your responsibility. The repository includes a scheduled workflow that takes a weekly compressed dump and retains it as a build artifact — a reasonable baseline for a personal instance.

Taking a backup

Any standard MongoDB dump works:

mongodump --uri="$MongoDB_URI" --archive=watcher-backup.gz --gzip

Handle the dump like a credential

It contains your watch conditions, everything Watcher collected as evidence, account records, and encrypted key material. Store it somewhere private, and pass the connection string through the environment rather than typing it into a command line where it lands in shell history.

Restoring

1. Stop anything that writes — pause the scheduled job and stop the service. Restoring underneath a running scheduler produces a mess.

2. Restore the archive:

   mongorestore --uri="$MongoDB_URI" --archive=watcher-backup.gz --gzip

3. Check the encryption key. Stored API keys are encrypted with CONFIG_ENCRYPTION_KEY. Restoring the data to an environment with a different key means those keys cannot be decrypted — they will be skipped with a warning and Watcher falls back to environment keys.

4. Sanity-check before resuming: pnpm watches:list shows your watches, and pnpm watches history <id> shows history from before the backup.

5. Resume the scheduler.

Restoring to a point before recent alerts

If your backup predates alerts you already received, the restored state does not know about them and they may be re-sent. Options:

• Accept one noisy run — usually simplest for a personal instance.
• Disable the affected watches, let one run pass to re-learn current content, then re-enable. You will miss anything that changes in that window.

A minimal disaster-recovery plan

Keep	Where
Watch definitions as YAML	Version control
Environment configuration (names, not values)	Documented alongside
Secrets	Your platform’s secret store, or a password manager
A recent database dump	Off the database host

With those four, a total loss is a rebuild of an hour, not a rewrite.

What is not backed up anywhere

Per-process key cooldowns and rate-limiter windows are in memory and are simply lost. They self-heal; there is nothing to restore.