Migrating from v0.7

ChannelWatch v1.0 is the first production release and introduces breaking changes from v0.7. The upgrade process is designed to be safe: migration runs automatically on startup, a backup is written before any data is touched, and you have a 30-day window to roll back if something goes wrong.

What changes in v1.0

The most significant change for existing users is the move from a single-DVR configuration to the new dvr_servers list format. v1.0 supports multiple Channels DVR servers from one ChannelWatch instance, and the internal config schema was updated to reflect this.

Other notable changes:

• Legacy environment variables dropped: CHANNELS_DVR_HOST and CHANNELS_DVR_PORT are no longer used. If they are present in your compose file, ChannelWatch will log a loud warning on startup and auto-populate dvr_servers[0] from their values, but you should remove them and configure your DVR through the web UI.
• SQLite activity database: Activity history is now stored in /config/channelwatch.db instead of a JSON file. The migration converts your existing history automatically.
• Encrypted credential storage: API keys and notification provider credentials are now encrypted at rest using /config/encryption.key (auto-generated on first startup).

How automatic migration works

When ChannelWatch v1.0 starts against an existing v0.7 config directory, it:

1. Detects the schema version in settings.json (v0.7 uses schema version 6).
2. Writes a full backup of your current settings.json to /config/backups/settings.v6.{timestamp}.json before making any changes.
3. Writes a migration journal entry (/config/migration.journal) marking the step as started.
4. Migrates your single-DVR config into the dvr_servers list format, preserving your host, port, and display name.
5. Converts activity_history.json to SQLite (if present), writing to a new channelwatch.db.new file, running an integrity check, then atomically renaming it to channelwatch.db.
6. Updates the schema version to 7 and marks the migration journal as completed.

If the container is killed mid-migration (e.g. a power loss), the next startup reads the journal and either resumes from the last completed step or rolls back to the pre-migration backup. Your original data is never deleted until the migration completes successfully.

Note

The atomic write strategy (write to temp file, integrity check, then rename) means a partial migration cannot leave your config in a broken state. Either the migration completes fully, or it rolls back cleanly.

The dvr_servers format

After migration, your settings.json will contain a dvr_servers list instead of the old top-level host/port fields:

{
  "_version": 7,
  "dvr_servers": [
    {
      "id": "a1b2c3d4",
      "host": "192.168.1.100",
      "port": 8089,
      "display_name": "My DVR",
      "api_key": null
    }
  ]
}

The id field is a stable 8-character identifier derived from the host and port. It stays the same across restarts and is used to associate activity history, metrics labels, and notification routing with a specific DVR server.

You do not need to edit this file directly. The web UI manages dvr_servers through Settings > DVR Servers.

Legacy environment variables

If your v0.7 compose file includes CHANNELS_DVR_HOST or CHANNELS_DVR_PORT, ChannelWatch v1.0 will:

1. Log a warning on startup listing the dropped variables and their v1.0 replacements.
2. Auto-populate dvr_servers[0] from the env var values so your DVR connection still works.

You should remove these variables from your compose file and verify the DVR connection through the web UI. The auto-population is a one-time convenience, not a permanent fallback.

Caution

Do not use CHANNELS_DVR_HOST or CHANNELS_DVR_PORT in new deployments. They are dropped in v1.0 and will be removed entirely in a future release. Use the web UI or the CW_DVR_<N>_HOST / CW_DVR_<N>_PORT environment variable family for multi-DVR configuration.

30-day rollback window

Your pre-migration backup is kept in /config/backups/ for 30 days. If you need to roll back to v0.7:

1. Stop the ChannelWatch container.
2. Copy /config/backups/settings.v6.{timestamp}.json back to /config/settings.json.
3. Delete /config/channelwatch.db (the SQLite database is not compatible with v0.7).
4. Switch your image tag back to coderluii/channelwatch:0.7 in your compose file.
5. Start the container.

After 30 days, the background cleanup job hard-deletes old backup files. If you need to roll back after that window, you will need a manual backup you made before upgrading.

Caution

Rolling back after 30 days is not supported without a manual backup. If you are uncertain about the upgrade, make a manual copy of your entire /config directory before pulling the v1.0 image.

Step-by-step upgrade

1. Back up your config directory

cp -r /your/local/path /your/local/path.backup-$(date +%Y%m%d)

This is a precaution on top of the automatic backup. Keep it until you’re satisfied with v1.0.

2. Pull the v1.0 image

docker compose pull

3. Start the container

docker compose up -d

Watch the logs during the first startup to confirm migration completes:

docker logs -f channelwatch

You should see log lines indicating the schema migration ran and completed. If you had CHANNELS_DVR_HOST set, you will also see the legacy env var warning.

4. Verify in the web UI

Open http://your-server-ip:8501 and confirm:

• Your DVR server appears under Settings > DVR Servers with the correct host and port.
• The dashboard shows a connected status.
• Your notification providers are still configured (they are migrated automatically).

5. Remove legacy environment variables

Edit your docker-compose.yml and remove any CHANNELS_DVR_HOST or CHANNELS_DVR_PORT lines. Restart the container:

docker compose up -d

Troubleshooting migration issues

Migration warning in logs but app starts fine: This is expected if you had legacy env vars set. Remove them and restart.

“encryption.key missing” error: This means the /config volume mount is not pointing to the same directory as your v0.7 config. Check your compose file’s volume path.

“migration.journal shows started but not completed”: The container was killed mid-migration. Restart it. ChannelWatch will resume or roll back automatically.

Activity history missing after upgrade: The JSON-to-SQLite migration may have failed. Check logs for migration entries. Your original activity_history.json is preserved in /config/backups/ if you need to recover it.

Next steps

• First-Run Configuration — verify your settings after migration
• Multi-DVR Setup — add additional Channels DVR servers
• Troubleshooting — fix common post-upgrade issues