chmonitorGetting started
Run chmonitor against your ClickHouse instance in minutes — three environment variables and one command, via Docker or from source.
Point chmonitor at an existing ClickHouse instance and you have a dashboard. You need three environment variables and one command. Pick Docker for the fastest path, or run from source to develop against it.
Prerequisites
- A running ClickHouse instance reachable from where you deploy.
- A ClickHouse user with
SELECTonsystem.*— see ClickHouse user & grants. - Docker installed locally (for the Docker path below).
Quick start
Pull and run
Replace vX.Y.Z with a real release tag from GitHub releases:
docker run -d \
--name chmonitor \
-p 3000:3000 \
-e CLICKHOUSE_HOST=http://your-clickhouse-host:8123 \
-e CLICKHOUSE_USER=monitoring \
-e CLICKHOUSE_PASSWORD=your-password \
ghcr.io/chmonitor/chmonitor:vX.Y.ZDocker host networking
If ClickHouse runs on the same Docker host, use the host gateway address instead of localhost. On Linux that is typically 172.17.0.1; on Mac/Windows use host.docker.internal.
Open the dashboard
Navigate to http://localhost:3000. The overview page loads immediately.
Clone and install
git clone https://github.com/chmonitor/chmonitor
cd clickhouse-monitoring
bun installConfigure environment
Copy .env.example to .env.local and fill in your ClickHouse connection:
CLICKHOUSE_HOST=http://your-clickhouse-host:8123
CLICKHOUSE_USER=monitoring
CLICKHOUSE_PASSWORD=your-passwordSee the local development guide for the complete setup including testing and building.
Verify
The overview page should render metrics right away. If pages are empty or show errors:
- Check the container logs:
docker logs chmonitor(Docker path). - Confirm the ClickHouse user can query
system.query_logdirectly. - See Enable system tables if some tables are missing.
Troubleshooting
Empty pages or connection errors
An empty overview usually means the dashboard reached ClickHouse but the user lacks grants, or the connection itself failed. Verify the user has SELECT on system.* (ClickHouse user & grants), then confirm CLICKHOUSE_HOST is reachable from the container or process.
Related
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.
Authentication
Require login before accessing the dashboard.
AI agent
Set up natural-language queries about your cluster.
Local development
Develop from source with hot reload.