chmonitor

chmonitor is an operational advisor for ClickHouse — not just a metrics viewer. It reads system.* and recommends projections, skip indexes, partition keys, PREWHERE rewrites, and materialized views (it recommends, and never auto-applies DDL), on top of the real-time query/cluster/replication monitoring you'd expect. Managed-ClickHouse AI tools stay locked to their own Cloud; chmonitor works the same way on Docker, Kubernetes, bare metal, or ClickHouse Cloud — self-host it free (GPL-3.0) or use the hosted Cloud, same codebase either way.

Upgrading from v0.2? v0.3 rebuilds the app on TanStack Start. ClickHouse connection vars are unchanged; browser vars move from NEXT_PUBLIC_* to VITE_* (old names still work as a fallback). See Upgrading to v0.3 below or the full Migrate to v0.3 guide.

Features

Self-hosted (OSS) vs Cloud (SaaS)

Same codebase, same features — the only difference is who runs it. See Editions for the open-core feature gates.

Quick start

One container, pointed at any reachable ClickHouse (OSS, Altinity, or ClickHouse Cloud):

docker run -d --name chmonitor -p 3000:3000 \
  -e CLICKHOUSE_HOST=https://clickhouse.example.com:8443 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=change-me \
  ghcr.io/chmonitor/chmonitor:latest

Open http://localhost:3000. Pin a release tag instead of latest for production.

Just want to look first? The live demo is at dash.chmonitor.dev — no setup required. Other targets (Cloudflare Workers, one-click Railway/Render/Fly, Kubernetes) are under Deployment.

Deployment

To self-host, run it next to your ClickHouse with the same CLICKHOUSE_* connection vars on any of these targets:

• Docker — one docker run; the fastest path to a live dashboard.
• Cloudflare Workers — global edge deploy (how the demo at dash.chmonitor.dev runs).
• One-click templates — Railway, Render, Fly.io.
• Kubernetes (Helm) — for clusters.

Prefer to look before you install? Try the live demo above — no setup required.

Cloudflare Workers

This project supports deployment to Cloudflare Workers with static site generation and API routes.

Prerequisites:

• Node.js 18+ and pnpm (bun is still used internally as the test runner and for .ts scripts)
• Cloudflare Workers account
• Wrangler CLI: npm install -g wrangler

Setup:

1. Clone and install dependencies:

git clone https://github.com/chmonitor/chmonitor.git
cd chmonitor
pnpm install

2. Configure environment variables in .env.local:

CLICKHOUSE_HOST=https://your-clickhouse-host.com
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=yourpassword
CLICKHOUSE_TZ=UTC

Optional API-key protection for /api/v1/* routes:

CHM_API_KEY_SECRET=your-signing-secret

Optional Clerk UI/session support (set at build time; NEXT_PUBLIC_* is the v0.2 fallback):

CHM_AUTH_PROVIDER=clerk
VITE_AUTH_PROVIDER=clerk
VITE_CLERK_PUBLISHABLE_KEY=pk_live_your_key
CLERK_SECRET_KEY=sk_live_your_key

Feature permissions default to enabled and public. Add sparse overrides when a deployment should hide or protect a feature:

# /etc/clickhouse-monitor/config.toml
[features.agent]
access = "authenticated"

[features.metrics]
enabled = false

access = "guest" is accepted as an alias for access = "public".

CHM_CONFIG_FILE=/etc/clickhouse-monitor/config.toml
# or env-only:
CHM_FEATURE_AGENT_ACCESS=authenticated
CHM_DISABLED_FEATURES=settings,metrics

Leave auth provider env unset or set it to none for self-hosted deployments without auth.

3. Deploy to Cloudflare Workers:

# Set CLOUDFLARE_API_TOKEN in .env.production.local or export it
# OR use OAuth: npx wrangler login

# Unified deploy (config, build, deploy, cache — same as CI)
pnpm run cf:deploy

Manual Deployment Steps:

# Step by step (same as CI)
pnpm run cf:config        # Set secrets from .env.production.local
cd apps/dashboard
pnpm run build            # Vite build → native Workers bundle (+ tsc --noEmit)
wrangler deploy --minify

Important Notes:

• Built with Vite + @cloudflare/vite-plugin into a native Workers bundle — no OpenNext, no KV/R2/D1 cache-population step
• TanStack Start + React 19 (the v0.2 Next.js app was retired in v0.3)
• Static shell is pre-rendered at build time; data is fetched client-side for edge CDN caching
• API routes run on Workers using the Fetch API
• Supports multi-host monitoring with query parameter routing (?host=0)

Docker

docker run -d \
  -p 3000:3000 \
  -e CLICKHOUSE_HOST=https://your-clickhouse-host.com \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=yourpassword \
  ghcr.io/chmonitor/chmonitor:latest

Releases

Tagged releases are built by GitHub Actions from tags matching v*. The release page includes:

• Docker images published to ghcr.io/chmonitor/chmonitor with the release version tag
• a Node.js standalone archive (*-standalone.tar.gz, the Nitro node-server output) for self-hosted Node deployments
• a Cloudflare Workers archive (*-cloudflare.tar.gz) for manual inspection or deployment
• generated release notes with CLI command usage, Docker tags, deployment steps, and checksums

For repeatable Docker deploys, prefer the versioned image tag from the release page instead of latest.

Upgrading to v0.3

v0.3 rebuilds the dashboard on TanStack Start. Features, routes, and ClickHouse setup carry over unchanged. The only env change is the browser variable prefix, and the old names keep working: