Backup & Restore

ChannelWatch includes a one-button backup and restore system in the web UI. A backup zip captures everything needed to move your installation to a new machine or recover from a corrupted database.

What’s in a backup

A backup zip contains:

File	Contents
`settings.json`	All configuration: DVR servers, notification providers, alert thresholds. DVR API keys are stored encrypted (the encryption key is in the zip separately).
`channelwatch.db`	The SQLite database: alert history, notification delivery log, session state, user accounts (if RBAC is enabled).
`session_state_<id>.json`	Per-DVR session state files. One file per configured DVR.
`encryption/encryption.key`	The encryption key used to protect DVR API keys in `settings.json`. Stored in a separate subfolder with a warning README.

Downloading a backup

Open the ChannelWatch web UI at http://your-server-ip:8501.
Go to Settings > Backup & Restore.
Click Download backup.

The browser downloads a zip file named channelwatch-backup-{timestamp}.zip. The download streams directly from the container; no temporary file is written to the host.

Restoring from a backup

Before writing any files, ChannelWatch automatically snapshots your current state to /config/backups/pre-restore.{timestamp}.zip. If the restore goes wrong, you can recover from that snapshot.

To restore:

Go to Settings > Backup & Restore.
Click Restore from backup and select your backup zip.
ChannelWatch validates the zip integrity and schema version.
If validation passes, it writes the files to /config/ and triggers a hot reload.

The web UI will briefly disconnect during the hot reload and reconnect automatically within a few seconds.

Schema version compatibility

ChannelWatch will not restore a backup whose schema version is ahead of the current application version. If you see a “schema version mismatch” error, you need to upgrade ChannelWatch first, then retry the restore.

Restoring a backup from an older version is supported. The migration runs automatically during the restore.

Automatic backups before migrations

ChannelWatch creates automatic backups before any schema migration. These are stored in /config/backups/ with names like settings.v6.{timestamp}.json. They are retained for 30 days and then pruned automatically.

If a migration fails partway through, you can recover by restoring the pre-migration backup from /config/backups/.

Moving to a new machine

A backup zip is fully portable. To move ChannelWatch to a new machine:

Download a backup from the old machine.
Set up ChannelWatch on the new machine with a fresh /config volume.
Complete the first-run wizard (or skip it if you’re restoring immediately).
Go to Settings > Backup & Restore and restore the backup zip.

After the restore, ChannelWatch will have all your DVR servers, notification providers, and alert history from the old machine.

Manual recovery (advanced)

If the web UI is unavailable and you need to restore manually:

Stop the container: docker compose down
Extract the backup zip to a temporary directory.
Copy settings.json and channelwatch.db to your /config volume path on the host.
Copy encryption/encryption.key to /config/encryption.key.
Set permissions: chmod 600 /your/config/path/encryption.key
Start the container: docker compose up -d

ChannelWatch will detect the restored files on startup and run any necessary migrations.

doctor CLI - validate your config and database integrity before a restore
Privacy - what data ChannelWatch stores and where
Common Issues - fixes for startup failures and other problems