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 is the primary supported install path today.

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 Docker hosts, 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. On a fresh install, ChannelWatch opens its first-run setup flow so you can add your Channels DVR server in the web UI.

The container exposes port 8501 and the published image defines a built-in healthcheck against http://localhost:8501/api/health.

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 and add extra_hosts: ["host.docker.internal:host-gateway"] on Linux. Automatic DVR discovery over mDNS/Bonjour is also unreliable in bridge mode, it can return no results without a clear error. Host networking is the safer choice if you want auto-discovery to work.

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	Reserved key file used by ChannelWatch security features on installs that have it
/config/logs/	Application logs
/config/backups/	Automatic pre-migration backups
/config/plugins/notifications/	Optional notification provider plugins

Caution

If your /config directory contains encryption.key, keep it with the rest of the config data and include it in backups. Treat it as the decrypting credential for Fernet-encrypted DVR API keys in settings.json, and protect it with strict permissions.

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"

PUID and PGID are most useful on NAS and appliance-style hosts such as Synology, Unraid, and TrueNAS SCALE, where the Docker daemon often writes mounted files as a non-login service user by default. Set both values to the UID and GID that should own the /config directory on the host if you see permission errors or root-owned files after first start.

Caution

CHANNELS_DVR_HOST and CHANNELS_DVR_PORT are legacy variables from older installs. Don’t use them for new deployments, and remove them during upgrades once your DVR is configured in the web UI. See Migrating from v0.7 for the current upgrade and rollback guidance.

DNS configuration

If your Channels DVR server is reachable by a short hostname, for example 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 migrates /config/settings.json automatically on startup. A timestamped backup is written to /config/backups/ before any migration step runs. See Migrating from v0.7 for version-pinning, rollback, and downgrade caveats.

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 — compare Pushover, Discord, Telegram, and more