Skip to content
ChannelWatch

Hot Reload

ChannelWatch v0.9.10 can reload many runtime settings without recreating the container. The supported path is: save settings in the web UI, let the UI backend signal the core process with SIGHUP, and let the core compare the old and new /config/settings.json snapshots.

What happens on save

Section titled “What happens on save”

When settings are saved through the web UI:

  1. The UI backend writes /config/settings.json.
  2. The UI backend asks supervisor for the core process ID.
  3. The UI backend sends SIGHUP to the core process.
  4. The core computes a structured diff between the previous and current settings.
  5. The core restarts only the affected DVR monitor tasks, unless the changed keys require a full container restart.

The core log summary starts with CONFIG_RELOADED and lists added, removed, changed, global, and restart-required settings.

Reload behavior

Section titled “Reload behavior”
Change typev0.9.10 behavior
DVR addedNew DVR monitor is initialized and started.
DVR removed or archivedExisting DVR monitor is stopped and watchdog state is removed.
DVR host, port, name, enabled state, or overrides changedThat DVR monitor is stopped, rebuilt, restarted, and freshness-checked.
Non-restart-required global settings changedActive DVR monitors restart so they inherit the updated shared settings.
No actionable changeNo monitor restart is performed.

If a restarted DVR monitor does not publish a freshness update within the verification window, ChannelWatch logs the failure and can send a hot-reload failure notification through the configured notification manager.

Restart-required settings

Section titled “Restart-required settings”

These keys are detected during hot reload, logged as restart-required, and not applied hot:

KeyWhy restart is required
uvicorn_hostThe UI web server bind address is chosen at process startup.
uvicorn_portThe UI web server port is chosen at process startup.
db_urlDatabase connection setup is process-level.
rbac_enabledAuth-layer initialization is process-level.
multi_dvr_v2_enabledFeature-gate changes require full runtime initialization.

To apply one of those settings, restart the container:

Terminal window
docker compose down
docker compose up -d

Direct file edits

Section titled “Direct file edits”

The web UI is the recommended path because it validates settings and sends the reload signal. If you edit /config/settings.json directly, keep a backup and either send SIGHUP yourself or restart the container.

Terminal window
docker kill --signal=HUP channelwatch

If the core has not initialized any DVR monitor yet, a reload signal may not be enough to turn a fresh no-DVR startup into an active monitoring runtime. In that case, restart the container after saving the first DVR.

Notification plugins

Section titled “Notification plugins”

Notification provider plugins are loaded during notification-manager initialization. Restart the container after adding or changing plugin files in /config/plugins/notifications/; this is the clearest way to ensure every DVR monitor sees the updated plugin set.

Section titled “Related pages”