Local Development

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

1. Clone the repo

git clone https://github.com/duyet/clickhouse-monitoring
cd clickhouse-monitoring

2. Install dependencies

The project uses Bun. Install it first if you don’t have it.

bun install

3. Create .env.local

In apps/dashboard/, create .env.local:

## Required
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_events

Client-side variables in the TanStack app use 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`

Client vars are inlined at build time. Never put secrets in VITE_* variables.

4. Configure ClickHouse

Make sure the user you set in step 3 has the right grants. See:

5. Start the dev server

cd apps/dashboard
bun run dev

Open http://localhost:3000.

Common issues

localhost connection refused — If ClickHouse is not running locally, update CLICKHOUSE_HOST to point at your remote instance.

Type errors on first run — Run bun run type-check from the repo root. Some generated types require a build pass first.

Missing system tables — See Enable system tables.