Install (Docker Compose)

ChannelWatch ships as a multi-arch Docker image and is designed to run as a single container managed by Docker Compose. This page covers everything you need to go from zero to a running instance.

Prerequisites

• Docker Engine 24+ and Docker Compose v2 (the docker compose plugin, not the legacy docker-compose binary)
• A running Channels DVR server reachable from the Docker host
• A local directory to store ChannelWatch configuration and logs (e.g. /opt/channelwatch/config)

Supported architectures

The coderluii/channelwatch:latest image is a multi-platform manifest that automatically selects the right variant for your hardware:

Architecture	Typical hardware
linux/amd64	Standard x86-64 servers, NAS devices, PCs
linux/arm64	Raspberry Pi 4/5, Apple Silicon (via Rosetta), modern ARM servers
linux/arm/v7	Older Raspberry Pi (32-bit OS), some NAS devices

No flags or extra steps are needed. docker compose pull picks the correct image automatically.

Compose file

Create a docker-compose.yml in a directory of your choice:

name: ChannelWatch
services:
  channelwatch:
    image: coderluii/channelwatch:latest
    container_name: channelwatch
    init: true
    network_mode: host
    volumes:
      - /your/local/path:/config
    environment:
      TZ: "America/New_York"
    restart: unless-stopped

Replace /your/local/path with the absolute path to your config directory. The TZ value should match your local timezone (IANA format, e.g. America/Chicago, Europe/London).

Note

All DVR connection settings are configured through the web UI after first launch. You do not need to set DVR host or port as environment variables.

Start the container

docker compose up -d

Then open http://your-server-ip:8501 in a browser. The first-run wizard will guide you through adding your Channels DVR server.

View logs

docker logs -f channelwatch

Host vs bridge networking

The default compose file uses network_mode: host, which lets ChannelWatch reach your Channels DVR server using localhost or any LAN IP without extra configuration. This is the simplest option for most home lab setups.

If you prefer bridge networking (for network isolation or port remapping), replace the network_mode line with explicit port mapping:

    # Remove: network_mode: host
    ports:
      - "8501:8501"

Caution

In bridge mode, you cannot use localhost as the DVR host. Use the LAN IP address of the machine running Channels DVR instead. If ChannelWatch and Channels DVR run on the same Docker host, use host.docker.internal (Linux: requires --add-host=host.docker.internal:host-gateway in the compose file).

Volume mounts

ChannelWatch stores all persistent data under /config inside the container. The directory you mount there will contain:

Path	Contents
/config/settings.json	All configuration (DVR servers, alert toggles, notification providers)
/config/channelwatch.db	SQLite activity history database
/config/encryption.key	Auto-generated key for encrypting stored credentials (chmod 0600, do not delete)
/config/logs/	Application logs
/config/backups/	Automatic pre-migration backups
/config/plugins/	Optional notification provider plugins

Caution

Do not delete encryption.key. ChannelWatch generates this file on first startup and uses it to encrypt any API keys or credentials you store. If the file is missing on a subsequent startup, the application will refuse to start with a clear error message rather than silently decrypting with a wrong key.

Optional environment variables

Most settings live in the web UI. A small set of environment variables are available for automation or headless deployments:

    environment:
      TZ: "America/New_York"

      # User/group IDs (match your host user to avoid permission issues)
      # PUID: "1000"
      # PGID: "1000"

      # Log verbosity: 0=minimal, 1=standard (default), 2=verbose
      # CW_LOG_LEVEL: "1"

      # Notification providers (can also be set in the web UI)
      # CW_APPRISE_DISCORD: "webhook_id/token"
      # CW_APPRISE_PUSHOVER: "user_key@api_token"
      # CW_APPRISE_TELEGRAM: "bot_token/chat_id"
      # CW_APPRISE_SLACK: "token_a/token_b/token_c"
      # CW_APPRISE_GOTIFY: "hostname/token"
      # CW_APPRISE_EMAIL: "user:pass@smtp.example.com"
      # CW_APPRISE_EMAIL_TO: "recipient@example.com"
      # CW_APPRISE_MATRIX: "user:pass@hostname/#room"
      # CW_APPRISE_CUSTOM: "apprise://custom-url"

      # Alert toggles (all enabled by default)
      # CW_ALERT_CHANNEL_WATCHING: "true"
      # CW_ALERT_VOD_WATCHING: "true"
      # CW_ALERT_DISK_SPACE: "true"
      # CW_ALERT_RECORDING_EVENTS: "true"

      # Disk space thresholds
      # CW_DS_THRESHOLD_PERCENT: "10"
      # CW_DS_THRESHOLD_GB: "50"
      # CW_DS_ALERT_COOLDOWN: "3600"

DNS configuration

If your Channels DVR server is reachable by a short hostname (e.g. media-server instead of a full IP), you can configure DNS search domains:

    dns_search: localdomain
    # Tailscale users: add your Tailnet domain
    # dns_search: localdomain tail12345.ts.net

If DNS resolution fails entirely, override the DNS servers directly:

    dns:
      - 1.1.1.1
      - 8.8.8.8

Upgrading

Pull the latest image and restart:

docker compose pull
docker compose up -d

ChannelWatch automatically migrates your configuration on startup. A backup of your previous settings is written to /config/backups/ before any migration step runs. See Migrating from v0.7 for details on the v0.7 to v1.0 upgrade path.

Security hardening (optional)

To prevent supervisor credentials from ever touching disk, mount /run/channelwatch as a tmpfs:

    tmpfs:
      - /run/channelwatch:mode=0750,uid=0,gid=1000

Next steps

• First-Run Configuration — add your Channels DVR server and configure alerts
• Multi-DVR Setup — monitor multiple Channels DVR servers from one instance
• Notification Providers — set up Pushover, Discord, Telegram, and more