YAML and Env Var Config

Caution

YAML and environment variable configuration for multi-DVR is a v1.0 feature. The exact field names and merge behavior described here reflect the locked design decisions in the v1.0 plan and may be refined before final release.

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 are fully equivalent — 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 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 encrypted; see note below)

Caution

Storing an API key in dvrs.yaml writes it to disk in plaintext inside your config volume. ChannelWatch encrypts the key in settings.json after the first load, but the YAML file itself is not encrypted. If you need to store API keys, prefer the web UI or use the env var method with Docker secrets.

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).

Note

The legacy CHANNELS_DVR_HOST and CHANNELS_DVR_PORT environment variables from v0.7 are not supported in v1.0. ChannelWatch logs a startup warning if it detects them. Use CW_DVR_1_HOST and CW_DVR_1_PORT instead, or configure the server through the web UI.

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

When deploying with the ChannelWatch Helm chart, DVR servers can be configured via the dvrs values key, which maps directly to the YAML format above. Sensitive values (API keys) should be stored in a Kubernetes Secret and referenced via valueFrom.secretKeyRef.

See the Helm chart’s values.yaml for the full schema.

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