YAML and Env Var Config

Caution

YAML and environment variable configuration for multi-DVR is a v1.0 feature. Field names and merge behavior are implemented in the current code path shown on this page.

The web UI is the primary way to manage DVR servers, but ChannelWatch also supports two file-based configuration paths for automated or headless deployments: a YAML config file and a family of environment variables. All three methods feed the same DVR list, and you can use any combination of them.

Configuration priority

When ChannelWatch starts, it merges DVR server definitions from all three sources in this order:

1. /config/dvrs.yaml — file-based config, loaded from the mounted config volume
2. CW_DVR_<N>_* environment variables — inline config from the compose file or future Kubernetes manifest
3. Web UI — servers added or edited through the browser

Servers defined in YAML or env vars are merged with servers already saved in settings.json. A server from YAML that matches an existing web-UI entry (same host and port) updates the existing entry rather than creating a duplicate. Servers added through the web UI that are not in YAML or env vars are preserved as-is.

Note

Removing a server from dvrs.yaml or unsetting its env vars does not delete it from ChannelWatch. The server remains in settings.json until you remove it through the web UI. This prevents accidental data loss from a config file edit.

YAML config file

Create /config/dvrs.yaml in your mounted config directory:

dvrs:
  - name: "Living Room"
    host: "192.168.1.10"
    port: 8089
    enabled: true

  - name: "Basement"
    host: "192.168.1.20"
    port: 8089
    enabled: true

  - name: "Office"
    host: "192.168.1.30"
    port: 8089
    enabled: false

YAML field reference

Field	Type	Required	Default	Description
name	string	No	Host address	Display name shown in notifications and the dashboard
host	string	Yes	—	IP address or hostname of the Channels DVR server
port	integer	Yes	—	Channels DVR API port (typically 8089)
enabled	boolean	No	true	Set to false to add the server in a disabled state
api_key	string	No	—	Per-DVR API key (stored in settings.json after import; see note below)

Caution

Storing an API key in dvrs.yaml writes it to disk in plaintext in that file. After ChannelWatch reads and saves the merged configuration, settings.json stores DVR API keys in encrypted form when the Fernet key is available, while UI values remain masked. Treat both dvrs.yaml and /config/encryption.key according to their sensitivity.

Environment variables

For compose-based deployments, you can define DVR servers using numbered environment variables. The <N> placeholder is a 1-based index (1, 2, 3, …).

environment:
  CW_DVR_1_NAME: "Living Room"
  CW_DVR_1_HOST: "192.168.1.10"
  CW_DVR_1_PORT: "8089"

  CW_DVR_2_NAME: "Basement"
  CW_DVR_2_HOST: "192.168.1.20"
  CW_DVR_2_PORT: "8089"

  CW_DVR_3_NAME: "Office"
  CW_DVR_3_HOST: "192.168.1.30"
  CW_DVR_3_PORT: "8089"
  CW_DVR_3_ENABLED: "false"

Env var reference

Variable	Required	Description
CW_DVR_<N>_HOST	Yes	IP address or hostname of the Channels DVR server
CW_DVR_<N>_PORT	Yes	Channels DVR API port
CW_DVR_<N>_NAME	No	Display name (defaults to host address if omitted)
CW_DVR_<N>_ENABLED	No	"true" or "false" (defaults to "true")
CW_DVR_<N>_API_KEY	No	Per-DVR API key

Indexes must be contiguous starting from 1. ChannelWatch stops scanning when it encounters a gap (e.g. if CW_DVR_3_HOST is missing, CW_DVR_4_HOST is ignored even if set).

Caution

CHANNELS_DVR_HOST and CHANNELS_DVR_PORT are deprecated compatibility variables. They were the single-DVR path in v0.7. In v1.0 they are not the current multi-DVR configuration surface and will not populate a DVR entry in the multi-DVR list. ChannelWatch logs a startup warning if it detects them. Replace them with CW_DVR_1_HOST and CW_DVR_1_PORT, or add the server through the web UI. If you are migrating from v0.7, remove these variables from your compose file before starting v1.0.

Hot reload

Changes to dvrs.yaml are picked up on hot reload without restarting the container. Environment variable changes require a container restart because Docker does not support live env var updates.

To trigger a hot reload after editing dvrs.yaml, use the Reload Config button in Settings > Advanced, or send SIGHUP to the ChannelWatch process:

docker kill --signal=HUP channelwatch

See Hot Reload for the full list of settings that support live reload.

Kubernetes and Helm

Caution

The app source now includes a Helm chart, but this page is still not the chart-values reference. The current chart is single-replica only, and the exact Kubernetes value surface should be taken from the chart’s values.yaml, not assumed from this page.

For Kubernetes deployments, use Kubernetes for the current chart shape and install flow. If you need to pass secrets such as shared API keys or bootstrap admin credentials, keep them in Kubernetes Secrets.

If you are using raw env-driven configuration in Kubernetes, verify the exact env var names against the app source and chart templates instead of assuming a dedicated dvrs values block.

Next steps

• mDNS Auto-Discovery — let ChannelWatch find servers on your LAN automatically
• Per-DVR Notification Routing — route different event types to different channels per server
• Hot Reload — apply config changes without restarting