Install on Bare-Metal Linux

ChannelWatch is primarily deployed as a Docker container. These steps show a direct Linux host install when you cannot or do not want to run Docker. ChannelWatch does not have a native package manager installer.

Before you start

Docker is the primary and best-tested deployment path. If Docker is an option on your host, use Install (Docker Compose) instead.

Use this page when you need a direct Linux service managed by systemd.

You will need:

A recent Linux distribution with systemd
Python 3 and venv
A local ChannelWatch checkout or release artifact on disk
A dedicated config path, such as /opt/channelwatch/config

Prepare the host

Create a dedicated service account and working directory, then build a Python virtual environment:

sudo useradd --system --home /opt/channelwatch --shell /usr/sbin/nologin channelwatch
sudo mkdir -p /opt/channelwatch /opt/channelwatch/config
sudo chown -R channelwatch:channelwatch /opt/channelwatch

python3 -m venv /opt/channelwatch/.venv
/opt/channelwatch/.venv/bin/pip install --upgrade pip

Install the application into that environment using the release artifact or source checkout you already have on the host.

Run ChannelWatch directly

The same Python entrypoint used by the container is available on bare metal:

/opt/channelwatch/.venv/bin/python -m channelwatch.main

Set a dedicated config path so ChannelWatch writes settings, logs, and backups outside the application code directory.

Create a systemd service

Use a unit like this as a starting point:

[Unit]
Description=ChannelWatch
After=network-online.target
Wants=network-online.target

[Service]
User=channelwatch
Group=channelwatch
WorkingDirectory=/opt/channelwatch
Environment=CONFIG_PATH=/opt/channelwatch/config
Environment=TZ=America/New_York
ExecStart=/opt/channelwatch/.venv/bin/python -m channelwatch.main
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Save it as /etc/systemd/system/channelwatch.service, then reload and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now channelwatch

Open the web UI

By default, ChannelWatch serves the web UI on port 8501:

http://your-linux-host:8501

Then complete First-Run Configuration.

Upgrading

Stop the service, update your local ChannelWatch code or artifact, refresh Python dependencies if needed, then start the service again.

Because this path runs outside Docker, make sure your backup routine includes /opt/channelwatch/config before you upgrade.