Updating ChannelWatch

Install ChannelWatch v1.5.3 normally once with Docker, Unraid, Compose, or Helm. This image installs the protocol 4 updater. After that, Settings > Updates can install compatible signed app and dependency package releases.

Why one image replacement is required

A release that introduces the protocol 4 updater requires one normal container image update. Every published v1.4.x image needs this replacement because its immutable launcher can import writable application code before the new package verification step. An in-app download cannot safely grant new verification authority to that old launcher.

v1.5.3 installs the image-owned verifier and launcher foundation. It does not publish an in-app runtime generation or downloadable Python package payload. Afterward, Update Center can install compatible signed app and official Python package releases only when each release provides one complete signed generation for the installed architecture.

Update the container to v1.5.3

The image update preserves settings, saved DVRs, history, RBAC configuration, the managed encryption key, and other data stored under /config. v1.5.3 does not require a settings schema migration.

Back up /config, keep its existing mount, and use the normal update path for your deployment.

Docker Compose

If your Compose file pins an image version, change it to coderluii/channelwatch:1.5.3. Then pull and recreate the service:

docker compose pull
docker compose up -d

Unraid

Open the Docker tab, update the ChannelWatch image to coderluii/channelwatch:1.5.3, then apply the update so Unraid pulls the image and recreates the container. Restarting the existing container alone does not apply a new image. Keep the existing appdata path mapped to /config.

Kubernetes and Helm

Set image.tag to 1.5.3 in the values file used by your existing single-replica release, then upgrade from the same chart source:

helm upgrade channelwatch ./deploy/helm/channelwatch \
  --namespace channelwatch \
  -f values.yaml

Keep the existing PersistentVolumeClaim mounted at /config.

What protocol 4 enables

After v1.5.3 is installed, a future compatible release can package the ChannelWatch app and its official Python packages as one signed runtime generation. Before publication, that generation must pass compatibility, restart, and rollback qualification on both AMD64 and ARM64. Update Center then selects the matching generation for the installed architecture, prepares it under /config, verifies it through the image-owned launcher, and restarts the ChannelWatch app processes inside the same container.

The application, frontend, and Python packages activate together. Core and UI must both report healthy for that exact generation. If activation fails, ChannelWatch restores the previous generation or the app copy in the image. Retry and Roll back remain available when the recorded job state permits them.

ChannelWatch Update Center showing v1.3.0 as current, the runtime ABI, trusted release status, and image-required update guidance — **Update Center**Update Center verifies compatible signed releases, records preparation and activation progress, and keeps Retry and Roll back actions with the update job. Captured from ChannelWatch v1.3.0 with safe demo data.

The default policy automatically installs eligible verified updates during the local 03:00–05:00 maintenance window. Installing the v1.5.3 image does not change the administrator’s selected automatic or notify-only policy.

v1.5.3 is not eligible for automatic installation because it is image-required. For a future compatible generation, automatic policy runs only when the signed release metadata explicitly permits automatic installation. Use Settings > Updates to check, apply an eligible compatible release, retry a failed job, or roll back.

Preparation and restart timing

Preparing a future dependency generation can take up to 10 minutes. ChannelWatch downloads and verifies the release, expands it into an inactive directory, and prepares the matching package environment before changing the active selection.

Activation then has a separate two-minute launcher validation deadline. The browser follows the same job for up to three minutes while Core and UI restart and validate. A brief disconnect during that time is expected. Leave the update job open and do not submit Apply again. If the job records a failure, correct the reported cause and use Retry.

Preparation requires writable, executable persistent storage. If /config is mounted with noexec, ChannelWatch stops before activation and leaves the previous runtime selected. Remount /config without noexec before retrying; installing packages into the image with pip or apt is not a supported workaround.

What still requires an image update

Protocol 4 does not replace every future container update. Use Docker, Unraid, Compose, or Helm when a release changes:

the Python interpreter;
the base image, operating system, or glibc;
Supervisor or container startup behavior;
the image-owned launcher or verifier;
runtime ABI, persistent schema, or deployment assumptions that are incompatible with the installed image.

Official relocatable Python builds are not currently available for both supported architectures, so interpreter replacement remains deferred to container images. ChannelWatch does not control the host Docker socket, run an external Docker controller, patch the image with apt or pip, or switch to an unverified fork to work around this boundary.

Installing v1.5.3 does not promise that every later release will be in-app. Update Center offers a generation only when the signed catalog includes complete compatible application and official package variants for the current architecture. Otherwise it shows container image update required.

Checking which runtime is active

For troubleshooting, channelwatch doctor runtime-info reports the app and Python built into the container image. The authenticated Update Center status API exposes worker_runtime for the responding app process and its verified generation. The command-line report can therefore show the image version after a successful in-app update.

Rollback and recovery

Rollback changes the active application and package generation, then restarts the ChannelWatch app processes. It does not restore old settings or database contents. Use Settings > Backup & Restore or your normal /config backup when you need to restore data.

The protocol 4 work strengthens verification and coordinates app-process restarts, but it does not establish the original cause of the restart report tracked in GitHub issue #22. That investigation remains open.

Auth-disabled installs

If CW_DISABLE_AUTH=true, anyone who can reach the UI can run admin operations, including updates and rollback. Keep auth-disabled installs on a trusted private network only.

Where update files live

Update runtime files live under /config/channelwatch-runtime/:

Path	Purpose
`active.json`	Active runtime generation pointer.
`latest.json`	Last trusted update manifest.
`rollback.json`	Previous runtime pointer and backup path.
`update-job.json`	Last update/check/rollback operation state.
`update.lock`	Single-flight update lock.
`releases/<generation-sha256>/`	Verified application and package generation.
`trust/<generation-sha256>.json`	Signed catalog retained for launcher verification.

Downloaded runtime generations are not included in normal app backup zips. Keep a separate /config backup routine for disaster recovery.