Hot Reload
You do not need to pull an image or recreate the container after changing normal settings. ChannelWatch has a core reload path, and the Settings UI also restarts the monitoring core after a successful save.
What happens when you save in the UI
Section titled “What happens when you save in the UI”- Save Settings sends the validated settings to the backend.
- The backend writes
/config/settings.jsonand signals the monitoring core withSIGHUP. - The Settings UI requests a core restart through Supervisor.
- The browser refreshes and returns to the dashboard.
This briefly restarts monitoring; it is not an image update or container recreation. Confirm the DVRs reconnect after the save. If the UI reports that settings were saved but the restart failed, inspect Diagnostics and the container logs before repeating changes.
Core reload behavior
Section titled “Core reload behavior”The core can compare old and new settings and rebuild only affected monitoring tasks. This is used by the backend’s reload signal and the core’s configuration watch. The log summary starts with CONFIG_RELOADED.
| Change | Core reload behavior |
|---|---|
| DVR added | Starts a new monitoring task. |
| DVR removed or archived | Stops its monitoring task and removes watchdog state. |
| DVR host, port, name, enabled state, or overrides changed | Rebuilds the affected DVR monitor. |
| Other reloadable global settings changed | Rebuilds active monitors with the updated shared settings. |
| No actionable change | Leaves monitoring tasks running. |
If a rebuilt monitor does not publish freshness within the verification window, the core logs a reload failure and can send a failure notification through configured providers.
Restart-required settings
Section titled “Restart-required settings”The core detects these keys but does not apply them through hot reload:
| Key | What needs reinitializing |
|---|---|
uvicorn_host / uvicorn_port |
UI server bind address or port. |
db_url |
Database connection setup. |
rbac_enabled |
Authentication initialization. |
multi_dvr_v2_enabled |
Runtime feature initialization. |
These are advanced settings, not a checklist of values to change. After an intentional change that requires full startup, restart the existing container:
docker compose restart channelwatchA restart keeps the current image and /config. Environment-variable or compose-definition changes instead require docker compose up -d so Docker applies the changed container configuration.
Direct file edits
Section titled “Direct file edits”Prefer the UI or authenticated settings API. If you manage /config/settings.json directly, back it up, preserve the other settings, and validate the JSON before saving. Restart the existing container when you need an explicit application of those edits:
docker compose restart channelwatchThe backend’s reload signal targets the core process directly. Do not assume docker kill --signal=HUP does the same: Docker targets the container’s init process, which is a different process in the supported image.
If no DVR monitor has initialized yet, restart the existing container after saving the first DVR rather than relying on reload alone.
Notification plugins
Section titled “Notification plugins”After adding or changing provider files in /config/plugins/notifications/, restart the container so every monitor initializes with the same plugin set. See Provider Plugins.