Migrating from v0.7

ChannelWatch v1.0 is the first production release and introduces breaking changes from v0.7. The upgrade flow is designed to be safe: migration runs automatically on startup, and a timestamped backup is written before ChannelWatch touches /config/settings.json.

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 are no longer the preferred path: remove CHANNELS_DVR_HOST and CHANNELS_DVR_PORT from older compose files and confirm your DVR settings in the web UI after the upgrade.
• SQLite activity database: Activity history is stored in /config/channelwatch.db in current releases.
• Credential wording changed: current public docs should describe stored API keys and provider credentials as masked in the UI and sensitive on disk. Don’t assume full encryption-at-rest behavior unless the app repo documentation says it is live.

How automatic migration works

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

1. Reads the existing configuration from /config/settings.json.
2. Writes a timestamped backup to /config/backups/ before any migration step runs.
3. Updates the on-disk configuration to the current release format.
4. Starts the upgraded application with your migrated settings.

The app repo migration guide does not promise a separate manual migration command. The expected path is still pull the new image, start the container, and verify the app after startup.

Note

The source-backed guarantee here is the backup in /config/backups/ before migration work begins. Keep your own manual copy of the full /config directory as well if you want the easiest rollback path.

The dvr_servers format

After migration, your settings.json will contain a dvr_servers list instead of the old top-level host and port fields. A simplified example looks like this:

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

The dvr_servers list is the current settings shape used by v1.0-era docs and features. After the upgrade, confirm your DVR entry looks correct in the web UI instead of editing settings.json by hand.

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 still includes CHANNELS_DVR_HOST or CHANNELS_DVR_PORT, remove them during the upgrade and verify the DVR connection through the web UI after the container starts.

Caution

Do not use CHANNELS_DVR_HOST or CHANNELS_DVR_PORT in new deployments. The current install docs treat the web UI as the source of truth for DVR connection settings.

Rollback and version pinning

The app repo migration guide recommends pinning production installs to a specific image tag and restoring a pre-upgrade backup before you start an older image. If you need to roll back after a bad upgrade:

1. Stop the ChannelWatch container.
2. Pin your compose file back to the last known-good image tag.
3. Restore the matching backup from /config/backups/ over /config/settings.json if settings were changed by the upgrade.
4. Start the container again.

For production, prefer immutable patch tags such as 1.0.3 over latest so you know exactly what version you can return to.

Caution

Older images may refuse to start if they see a newer settings schema. Restore the pre-upgrade backup before starting the older image, and keep a manual copy of the full /config directory if you want rollback coverage for settings, history, and any session-state files.

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

If you prefer a pinned upgrade instead of latest, update your compose file first and use a specific tag such as coderluii/channelwatch:1.0.3.

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 the container start cleanly. If the older config needs migration, ChannelWatch will handle it during startup.

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 still look correct.

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: verify the app in the web UI, then clean up any leftover legacy DVR env vars from your compose file.

App will not start after you pin back to an older image: restore the pre-upgrade backup from /config/backups/ before starting the older version. This matches the downgrade caveat in the app repo migration guide.

Missing settings after upgrade: double-check that the container is still mounted to the same /config directory you used before the upgrade, then restore from your manual backup or the timestamped backup in /config/backups/ if needed.

Need exact tag guidance: use the tag shapes from the app repo migration guide. MAJOR.MINOR.PATCH tags are immutable, MAJOR.MINOR rolls forward on patch releases, and latest always tracks the newest stable release.

Next steps

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