Backup & Restore

Use Settings > Backup to download your saved configuration and local state before an update, a storage move, or a recovery attempt. You need administrator access when secure login is enabled.

Backup and restore settingsBackup and restore tools include explicit restore warnings and a sanitized debug bundle download. Captured from ChannelWatch v1.6.0 with safe demo data.View full-size screenshot

Note

This page describes the shipped v1.6.5 backup and restore flow, including protected-credential support when /config/encryption.key is present.

What’s in a backup

A backup zip contains:

File	Contents
settings.json	The saved settings file, including DVRs, routing, provider configuration, and saved credentials. Protected values remain encrypted; other provider secrets can remain readable. This is not the masked settings response shown in the UI.
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.
sensitive_keys/encryption.key	Included when the key file exists, with a separate security warning. It can decrypt protected credentials from the matching settings file.
backup_manifest.json	Backup format, settings schema, key format, timestamp, and included-file list.

Normal app backup zips do not include downloaded Update Center app bundles under /config/channelwatch-runtime/releases/. Use a manual /config archive if you need to preserve downloaded bundle rollback state as well as settings and history.

Caution

Treat the backup zip as a secret. It contains your saved configuration and may also contain an encryption key that decrypts protected credentials. Store it somewhere safe, don’t email it, and don’t upload it to a public file host.

Downloading a backup

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

The browser downloads channelwatch_backup_<timestamp>.zip. Keep it outside the server you are backing up, and protect it like a password file.

Restoring from a backup

Before replacing your state, ChannelWatch creates a private snapshot at /config/backups/pre-restore.<timestamp>.<random-token>.zip. Keep that snapshot if you need to undo the restore.

The Update Center also creates a pre-update backup before applying a compatible app bundle. Those backups are stored under /config/backups/ and are separate from the active app-bundle rollback pointer.

Before you restore

Before you start, confirm you have the correct backup zip for this installation and keep a copy outside the current host before you upload it. If you can still open the archive on another machine, inspect settings.json there first to confirm it is valid JSON and that the timestamp matches the backup you intend to restore.

Running the restore

To restore:

1. Go to Settings > Backup.
2. Under Restore from backup, click Choose backup file… and select your backup ZIP.
3. ChannelWatch validates the zip integrity and schema version.
4. If validation passes, it writes the files to /config/ and triggers a hot reload.

After success, reload the page if it still shows old data. Recheck the restored accounts and sign in again if the restored database changed your session.

Schema version compatibility

ChannelWatch rejects a backup whose settings schema is newer than the running app supports. This checks the schema in the backup manifest, not just the version number printed on a release. If the schema is ahead, update ChannelWatch before trying again.

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

Verifying the restore

After the hot reload completes, verify the restore before you consider the system recovered:

1. Open Diagnostics and confirm System Status shows the backend as healthy.
2. Run Connection Tests to confirm the DVR host, port, and network path still work.
3. When you are ready to send a real sample notification, run one Diagnostic Tests > Notifications test and confirm receipt. Use the CLI fallback described in Diagnostics if the UI returns an unknown-test-name error.
4. Check the routes and settings you care about most, especially DVR entries, alert toggles, and disk-space thresholds.

If those checks fail, keep the error and review the matching pre-restore snapshot before making more changes. Do not repeatedly overwrite your only known-good copy.

Automatic backups before migrations

ChannelWatch creates safety copies during settings migrations under /config/backups/. A settings-only migration copy is not a full backup ZIP: it does not necessarily include the matching database, session files, or encryption key. Keep your own full backup generations rather than relying on migration copies as your backup schedule.

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

Backup rotation schedule

ChannelWatch creates safety snapshots before migrations, but it does not schedule your regular backup routine for you. For active installations, a weekly manual backup is a good default.

Also take a fresh backup before any upgrade, before major settings changes, and before moving the container or /config volume to new storage. Keep more than one generation so a bad backup does not replace your only good restore point.

Offsite and redundant storage

Do not keep the only backup copy on the same machine and disk that hold your DVR recordings. Store at least one copy somewhere else, such as a NAS, cloud storage account, or separate external drive.

Because the zip is portable, you don’t need special tooling to store it offsite, but you do need to protect it like any other sensitive config archive. A simple pattern is local copy plus one offsite copy plus one older known-good copy in rotation.

Moving to a new machine

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

1. Download a backup from the old machine.
2. Set up ChannelWatch on the new machine with a fresh /config volume.
3. Choose the fresh installation’s security mode and create an administrator if using secure login. You do not need to recreate every DVR entry before restoring.
4. Go to Settings > Backup and restore the backup ZIP.

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

Note

If your backup zip includes sensitive_keys/encryption.key, the restore process writes it to /config/encryption.key on the new machine so protected credentials continue to decrypt correctly.

Manual recovery (advanced)

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

1. Stop the container: docker compose down
2. Extract the backup zip to a temporary directory.
3. Inspect settings.json to confirm it is valid JSON before copying it into place.
4. Preserve the current config directory before replacing anything. Copy the archive’s settings.json, channelwatch.db, and included session_state_*.json files to the host path mounted as /config.
5. If the backup contains sensitive_keys/encryption.key, copy it to /config/encryption.key. Keep the key and settings from the same backup together.
6. Check ownership against your configured PUID and PGID. Set restrictive key permissions: chmod 600 /your/config/path/encryption.key.
7. Start the container: docker compose up -d.

These manual steps bypass the normal ZIP validation and transactional restore. Older archives with a legacy wrapped key may require the original storage key; copying that file alone is not a portable-key conversion. Prefer the web restore path, which can validate the key and handle supported legacy recovery options.

ChannelWatch will detect the restored files on startup and run any necessary migrations. After startup, use the Diagnostics tab to run Connection Tests and a test alert before you return the system to normal use.

Related pages

• Diagnostics - verify backend health, DVR connectivity, and test alerts after a restore
• Privacy - what data ChannelWatch stores and where
• Common Issues - fixes for startup failures and other problems