ClickHouse Monitoring Dashboard
A modern Next.js 15 dashboard that provides real-time insights into ClickHouse clusters through system tables. Features static site generation with client-side data fetching for optimal performance and CDN caching.
Features:
- Query Monitoring: Current queries, query history, resources (memory, parts read, file_open), expensive queries, most used tables/columns
- Cluster Overview: Memory/CPU usage, distributed queue, global settings, MergeTree settings, metrics
- Data Explorer: Interactive database tree browser with fast tab switching and column-level details
- Table Analytics: Size, row count, compression, part sizes with column-level granularity
- Visualization: 30+ metric charts for queries, resources, merges, performance, and system health
- Developer Tools: Zookeeper explorer, query EXPLAIN, query kill functionality
- Multi-Host Support: Monitor multiple ClickHouse instances from a single dashboard
Demo
The ClickHouse server running on my homelab so can be slow sometimes:
Deployment
Cloudflare Workers
This project supports deployment to Cloudflare Workers with static site generation and API routes.
Prerequisites:
- Node.js 18+ and Bun
- Cloudflare Workers account
- Wrangler CLI:
npm install -g wrangler
Setup:
- Clone and install dependencies:
git clone https://github.com/duyet/clickhouse-monitoring.git
cd clickhouse-monitoring
bun install
- 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
NEXT_PUBLIC_CHM_API_KEY=your-minted-dashboard-key
NEXT_PUBLIC_CHM_API_KEY is only needed when the browser dashboard should call protected API routes. It is visible to browser users.
- Deploy to Cloudflare Workers:
# Login to Cloudflare
npx wrangler login
# Set secrets and deploy
bun run cf:deploy
Important Notes:
- Build uses Webpack (not Turbopack) due to Cloudflare Workers compatibility
- Next.js version pinned to 15.5.x (React 19) for stability
- Static pages are pre-rendered at edge for optimal performance
- API routes run on Workers using Fetch API
- Supports multi-host monitoring with query parameter routing (
?host=0)
Manual Deployment Steps:
# Set secrets manually
bun run cf:config
# Build with webpack
bun run cf:build
# Deploy
wrangler deploy
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/duyet/clickhouse-monitoring:latest
Releases
Tagged releases are built by GitHub Actions from tags matching v*. The release page includes:
- Docker images published to
ghcr.io/duyet/clickhouse-monitoring with the release version tag
- a Next.js standalone archive for Node.js deployments
- a Cloudflare Workers/OpenNext archive 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.
Documentation