Skip to content
ChannelWatch

First-Run Configuration

When you open ChannelWatch for the first time on a fresh install, ChannelWatch guides you through the essential setup in the web UI. This page covers that first-run flow and the core settings you’ll configure.

Opening the web UI

Section titled “Opening the web UI”

After starting the container, open a browser and navigate to:

http://your-server-ip:8501

Replace your-server-ip with the IP address or hostname of the machine running ChannelWatch. If you’re running it locally, use http://localhost:8501.

First-run setup

Section titled “First-run setup”

On a fresh install with no existing configuration, ChannelWatch opens a guided first-run flow before the main dashboard. In v0.9.15, the flow starts with DVR discovery or manual entry, validates the connection, and saves at least one Channels DVR server before monitoring begins.

ChannelWatch first-run wizard prompting the operator to discover a Channels DVR server or add one manually
First-Run WizardThe first-run wizard appears when no DVR servers are configured. Captured from ChannelWatch v0.9.15 with safe demo data.
ChannelWatch first-run wizard manual DVR form filled with safe demo values and a successful connection test
Manual DVR AddManual setup supports a demo-safe name, host, port, optional API key, and connection test before saving. Captured from ChannelWatch v0.9.15 with safe demo data.

Step 1: Add your first Channels DVR server

Section titled “Step 1: Add your first Channels DVR server”

Enter the connection details for your Channels DVR server:

Field Description
Host IP address or hostname of your Channels DVR server (e.g. 192.168.1.100)
Port Channels DVR API port (default: 8089)
Display Name A friendly label shown in the dashboard (e.g. Living Room DVR)
API Key Optional. Required only if your Channels DVR server has API authentication enabled.

Click Test Connection to verify ChannelWatch can reach the server before saving.

Step 2: Timezone and system settings

Section titled “Step 2: Timezone and system settings”
Setting Description
Timezone Your local timezone in IANA format (e.g. America/New_York). Used for timestamps in notifications and logs.
Log Level Standard (default) logs connection events and alerts. Verbose adds detailed event processing output, useful for troubleshooting.
Log Retention How many days of logs to keep before automatic cleanup.

Step 3: Review and save

Section titled “Step 3: Review and save”

The wizard shows a summary of your settings. Click Save and Launch to write the configuration and start monitoring.

ChannelWatch then connects to your Channels DVR server and begins watching the event stream. The main dashboard appears once the initial setup is complete.

Core settings reference

Section titled “Core settings reference”

After the wizard, all settings are available under the Settings tab. The core DVR settings are:

Setting Description
DVR server list One row per configured Channels DVR server
Host and port Server IP or hostname plus API port, defaulting to 8089
API key Optional per-DVR key, encrypted when /config/encryption.key is available
Enabled Whether ChannelWatch should actively monitor that DVR
Timezone Local timezone for timestamps
Log Level Standard or Verbose logging
Log Retention Auto-cleanup period in days

Alert configuration

Section titled “Alert configuration”

ChannelWatch monitors four alert types. All are enabled by default. Toggle them under Settings > Alerts:

Alert type What it monitors
Channel Watching Live TV viewing sessions
VOD Watching Recorded content and library playback
Recording Events Recording lifecycle (scheduled, started, completed, cancelled, stopped)
Disk Space Free space on the DVR storage path

Each alert type has its own options page with toggles for what information to include in notifications (channel name, device name, program details, etc.).

Stream counting is part of Channel Watching configuration, not a separate fifth alert type.

Notification providers

Section titled “Notification providers”

ChannelWatch sends notifications through one or more providers. Configure them under Settings > Notifications. At least one provider must be configured for alerts to be delivered.

Supported providers are Pushover plus Apprise-backed destinations for Discord, Telegram, Slack, Email (SMTP), Gotify, Matrix, and any Apprise-compatible URL.

See the Notification Providers section for per-provider setup guides.

Verifying your setup

Section titled “Verifying your setup”

Use the Diagnostics tab to confirm everything is working:

  • System Status shows the health of each component (DVR connection, notification providers, alert system).
  • Connection Tests lets you manually test connectivity to each configured Channels DVR server.
  • Alert Tests sends a test notification for each alert type so you can confirm delivery end-to-end.

Configuration storage

Section titled “Configuration storage”

All settings are stored in /config/settings.json inside the container. You do not need to edit this file directly.

If you need to back up your configuration, copy the entire /config directory. The backup includes settings.json, the SQLite activity database, and any related runtime files. API keys and provider credentials should be treated as sensitive; per-DVR API keys are encrypted in settings.json when a valid /config/encryption.key is available.

Next steps

Section titled “Next steps”