chmonitorDeployment
Self-host (Node / standalone)
Run chmonitor on any server using Node.js — bare VMs, dedicated servers, or any environment where you manage the process directly.
Run chmonitor on any server using Node.js — best for bare VMs, dedicated servers, or any environment where you manage the process directly.
Prerequisites
- Node.js and pnpm (
pnpm@10.18.0, via corepack) installed on the server. - A reachable ClickHouse endpoint with a monitoring user.
- A process supervisor (systemd) and, optionally, a reverse proxy (nginx).
Setup
Clone and install
git clone https://github.com/chmonitor/chmonitor.git
cd chmonitor
pnpm installSet credentials
export CLICKHOUSE_HOST='https://clickhouse.example.com:8443'
export CLICKHOUSE_USER='monitoring'
export CLICKHOUSE_PASSWORD='change-me'Using .env
Put env vars in apps/dashboard/.env.local. Never commit credentials.
cat <<'EOF' > apps/dashboard/.env.local
CLICKHOUSE_HOST=https://clickhouse.example.com:8443
CLICKHOUSE_USER=monitoring
CLICKHOUSE_PASSWORD=change-me
EOF
pnpm run startVerify
curl -sf http://localhost:3000/api/healthz && echo OKConfigure
Required:
CLICKHOUSE_HOST=https://clickhouse.example.com:8443
CLICKHOUSE_USER=monitoring
CLICKHOUSE_PASSWORD=change-mePut them in apps/dashboard/.env.local. Template:
apps/dashboard/.env.example.
Full list: Environment variables.
systemd unit
[Unit]
Description=chmonitor ClickHouse dashboard
After=network.target
[Service]
Type=simple
User=chmonitor
WorkingDirectory=/opt/chmonitor
EnvironmentFile=/etc/chmonitor/env
ExecStart=/usr/local/bin/pnpm run start
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.targetCreate /etc/chmonitor/env:
CLICKHOUSE_HOST=https://clickhouse.example.com:8443
CLICKHOUSE_USER=monitoring
CLICKHOUSE_PASSWORD=change-me
CHM_AUTH_PROVIDER=noneEnable and start:
systemctl enable --now chmonitorUpgrading
cd /opt/chmonitor
git pull
pnpm install
pnpm run build
systemctl restart chmonitorFor breaking changes between major versions, see Migrating to v0.3.