chmonitorLocal development
Run the chmonitor dashboard from source with Bun and TanStack Start to develop and test changes before deploying.
Run chmonitor from source for development or to test changes before deploying.
The dashboard app
The dashboard is apps/dashboard (TanStack Start, v0.3+). Client env vars use the VITE_* prefix. The legacy Next.js app has been removed. The steps below target apps/dashboard.
Steps
Clone the repo
git clone https://github.com/chmonitor/chmonitor
cd clickhouse-monitoringCreate .env.local
In apps/dashboard/, create .env.local:
CLICKHOUSE_HOST=http://localhost:8123
CLICKHOUSE_USER=monitoring
CLICKHOUSE_PASSWORD=your-password
# Optional
CLICKHOUSE_NAME=local-dev
CLICKHOUSE_MAX_EXECUTION_TIME=60
CLICKHOUSE_TZ=UTC
EVENTS_TABLE_NAME=system.monitoring_eventsFor dual-surface settings you normally set the canonical CHM_* name once and the VITE_* is derived at build time (e.g. set CHM_AUTH_PROVIDER, not VITE_AUTH_PROVIDER). Client-side variables in the TanStack app use the VITE_* prefix. The Next.js app uses NEXT_PUBLIC_* for the same variables. For example:
TanStack (VITE_*) | Next.js (NEXT_PUBLIC_*) |
|---|---|
VITE_AUTH_PROVIDER | NEXT_PUBLIC_AUTH_PROVIDER |
VITE_CLERK_PUBLISHABLE_KEY | NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY |
VITE_TITLE_SHORT | NEXT_PUBLIC_TITLE_SHORT |
Never put secrets in VITE_* variables
Client vars are inlined at build time and shipped to the browser.
Configure ClickHouse
Make sure the user you set in the previous step has the right grants:
Verify
The dashboard should hot-reload as you edit source, and the overview page should render live metrics from your ClickHouse instance.
Troubleshooting
Common issues
localhostconnection refused — If ClickHouse is not running locally, updateCLICKHOUSE_HOSTto point at your remote instance.- Type errors on first run — Run
bun run type-checkfrom the repo root. Some generated types require a build pass first. - Missing system tables — See Enable system tables.
Related
Getting started
Run chmonitor against your ClickHouse instance in minutes.
ClickHouse user & grants
Create a safe read-only monitoring user with the minimal grants needed.
Enable system tables
Enable system log tables for full feature coverage.
Install & configure
Deploy to Kubernetes, Cloudflare Workers, or another platform.
Enable system tables
Enable and configure ClickHouse system log tables for full chmonitor feature coverage, including query_log, metric_log, and optional thread logs.
Features
Explore every chmonitor feature — query monitoring, storage, cluster health, metrics, and AI insights — with per-feature access control.