First-Run Configuration
When you open ChannelWatch for the first time, a guided wizard walks you through the essential setup steps. This page covers that wizard 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:8501Replace 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 wizard
Section titled “First-run wizard”On a fresh install with no existing configuration, ChannelWatch shows a full-screen wizard before the main dashboard. The wizard has three steps.
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. Default is 7 days. |
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 will connect to your Channels DVR server and begin watching the event stream. The main dashboard appears once the initial connection succeeds.
Core settings reference
Section titled “Core settings reference”After the wizard, all settings are available under the Settings tab. The core settings are:
| Setting | Description |
|---|---|
| Channels DVR Host | Server IP or hostname |
| Channels DVR Port | Server port (default: 8089) |
| 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 types of events. 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.).
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: Pushover, 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. The web UI writes to it atomically (write to a temp file, then rename) to prevent corruption if the container is stopped mid-save.
If you need to back up your configuration, copy the entire /config directory. The backup includes settings.json, the SQLite activity database, and the encryption key.
Next steps
Section titled “Next steps”- Multi-DVR Setup — add more Channels DVR servers
- Channel Watching Alerts — configure live TV alert options
- Notification Providers — set up push notifications
- Troubleshooting — fix common setup issues