Skip to content
ChannelWatch

Disaster Recovery

This page is for recovery situations where the normal web UI path is no longer available, or where a standard restore did not solve the problem. Start with the least destructive option that matches your situation.

When to use this page

Section titled “When to use this page”

Use this page when one of these is true:

  • The web UI is unreachable and the container will not start.
  • docker logs channelwatch shows database corruption or repeated startup failures tied to the local data store.
  • The host machine failed and you’re rebuilding on new hardware.

If the web UI is still available and you already have a backup zip, use Backup & Restore first. This page is the escalation path when the normal recovery flow is blocked.

Recovery option overview

Section titled “Recovery option overview”
SituationRecommended option
Backup zip available, web UI unavailableOption 1: Restore from backup zip
No backup zip, database corruption confirmedOption 2: Repair a corrupted database
No backup zip, repair failedOption 3: Rebuild from scratch
New hardware, backup zip availableOption 1: Restore from backup zip

Start with Option 1 whenever you have a valid backup zip. Options 2 and 3 are fallback paths for cases where no usable backup is available.

Option 1: Restore from backup zip

Section titled “Option 1: Restore from backup zip”

This is the preferred recovery path because it preserves your settings, database, session state, and encryption key in one package.

If the web UI is down but you still have a backup zip, follow the manual recovery steps in Backup & Restore. That page already covers:

  • stopping the container
  • extracting the backup zip
  • restoring settings.json, channelwatch.db, and encryption.key
  • restarting the container and letting ChannelWatch run any needed migrations

Use this same path when moving to a new machine after host failure. Set up a fresh ChannelWatch container with an empty /config volume, then restore the backup onto the new host.

If the restore fails with a schema compatibility error, go to Upgrade and Version Migration Troubleshooting.

Option 2: Repair a corrupted database

Section titled “Option 2: Repair a corrupted database”

Use this option only when you do not have a usable backup zip and channelwatch.db appears to be corrupted.

Checking integrity

Section titled “Checking integrity”
  1. Stop the container.
  2. Locate the host path that maps to /config.
  3. Run SQLite’s integrity check against channelwatch.db.
Terminal window
sqlite3 channelwatch.db "PRAGMA integrity_check;"

An ok result means the database file itself is structurally valid. If SQLite reports corruption, move on to the repair attempt below.

Attempting repair

Section titled “Attempting repair”

SQLite includes a recovery mode that can salvage readable rows from a damaged file.

  1. Keep the original channelwatch.db file unchanged until the repair attempt is complete.
  2. Run SQLite recovery on the host machine.
  3. Write the recovered output to a new database file, then replace the old file only after the new database opens cleanly.
Terminal window
sqlite3 channelwatch.db ".recover" | sqlite3 channelwatch-recovered.db

After recovery, run the integrity check against the new file:

Terminal window
sqlite3 channelwatch-recovered.db "PRAGMA integrity_check;"

If the repaired file returns ok, replace the old database with the recovered one, start the container, and run the verification checklist at the end of this page.

This path requires sqlite3 on the host machine. It can salvage alert history and delivery records, but it is not guaranteed to recover everything.

When repair fails

Section titled “When repair fails”

If .recover fails, produces another corrupt file, or the container still cannot start after the repaired database is in place, stop here and switch to Option 3: Rebuild from scratch.

Do not keep retrying destructive edits against the only remaining copy of the database. Preserve the original file for later analysis.

Option 3: Rebuild from scratch

Section titled “Option 3: Rebuild from scratch”

Use this option when you have no usable backup and database repair did not work.

What you lose

Section titled “What you lose”

Starting over means losing the local state stored in the old /config volume, including:

  • alert history
  • notification delivery log
  • session state

What you keep

Section titled “What you keep”

If you are rebuilding without a usable backup, you should assume that ChannelWatch itself is starting from zero. The information you can keep is whatever you can re-enter from outside ChannelWatch, such as:

  • DVR host and port details
  • DVR API keys
  • notification provider credentials
  • your preferred alert settings

Steps

Section titled “Steps”
  1. Preserve logs and any damaged config files before deleting anything.
  2. Remove or archive the old /config volume contents.
  3. Start a fresh ChannelWatch container with a clean /config volume.
  4. Complete the first-run setup again.
  5. Re-enter DVR servers, notification providers, and alert settings through the web UI.

If the container starts but you need help validating connectivity after the rebuild, use CLI Commands and Common Issues.

Preserving logs before recovery

Section titled “Preserving logs before recovery”

Before any destructive action, save the container logs to the host so you keep the failure details:

Terminal window
docker logs channelwatch > channelwatch-logs-$(date +%Y%m%d).txt

If the container still starts briefly before crashing, capture the logs before deleting the /config volume or replacing the database. That log file gives you a record of the original failure and is often the fastest way to confirm whether you were dealing with corruption, a permissions problem, or a migration issue.

After recovery: verification checklist

Section titled “After recovery: verification checklist”

After any recovery path succeeds, confirm that ChannelWatch is healthy before you consider the system restored:

  1. Open the web UI and check that the backend loads normally.
  2. Go to Diagnostics and run Connection Tests.
  3. Confirm System Status shows a healthy DVR connection.
  4. Send a test alert to verify that notification delivery still works.
  5. Review docker logs channelwatch for any WARN or ERROR lines during startup.

If any of these checks fail, review Backup & Restore, Upgrade and Version Migration Troubleshooting, and Common Issues before making more destructive changes.

Section titled “Related pages”