Local development

Run the chmonitor dashboard from source with pnpm 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-monitoring

Install dependencies

The project uses pnpm (pnpm@10.18.0) as its package manager. Install it first if you don't have it.

pnpm install

Create `.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_events

For 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 hosts

chmonitor connects to one or more ClickHouse instances. Comma-separated lists configure multiple hosts; each hostId maps positionally to the other lists.

# One host
CLICKHOUSE_HOST=http://localhost:8123
CLICKHOUSE_USER=monitoring
CLICKHOUSE_PASSWORD=your-password

# Multiple hosts (comma-separated, positional)
CLICKHOUSE_HOST=http://ch-1:8123,http://ch-2:8123,http://ch-3:8123
CLICKHOUSE_USER=monitoring,monitoring,monitoring
CLICKHOUSE_PASSWORD=pass-1,pass-2,pass-3
CLICKHOUSE_NAME=ch-1,ch-2,ch-3

Variable	Purpose
`CLICKHOUSE_HOST`	One or more URLs (`http://`/`https://`), optionally `host:port`.
`CLICKHOUSE_USER`	Comma-separated user(s); a single value applies to every host.
`CLICKHOUSE_PASSWORD`	Comma-separated password(s); a single value applies to every host.
`CLICKHOUSE_NAME`	Comma-separated display names for the host switcher.
`CLICKHOUSE_DATABASE`	Default database (default `system`).
`CLICKHOUSE_MAX_EXECUTION_TIME`	Query timeout in seconds (default `60`).
`CLICKHOUSE_TZ`	Session timezone for queries.
`CLICKHOUSE_EXCLUDE_USER_DEFAULT`	Hide the `default` user from the UI when set.

Host 0 is CLICKHOUSE_HOST's first entry and is the default in URLs (?host=0). Make sure the user has the grants described in the next step.

Configure Postgres hosts (optional)

Postgres support is a beta source engine — off by default. Turn it on with the feature flag, then add connection details the same positional way as ClickHouse:

# Master switch for Postgres as a source
CHM_FEATURE_POSTGRES_SOURCE=true

# One Postgres host
POSTGRES_HOST=db.example.com
POSTGRES_PORT=5432
POSTGRES_USER=chmonitor_ro
POSTGRES_PASSWORD=my-password
POSTGRES_DATABASE=postgres
POSTGRES_SSLMODE=require
POSTGRES_NAME=Production Postgres

# Multiple Postgres hosts (comma-separated, positional)
POSTGRES_HOST=db-1:5432,db-2:5432
POSTGRES_USER=ro,ro
POSTGRES_PASSWORD=p1,p2
POSTGRES_NAME=pg-1,pg-2

Variable	Purpose
`CHM_FEATURE_POSTGRES_SOURCE`	Master switch for Postgres monitoring. Default `false`.
`POSTGRES_HOST`	One or more hosts, optionally `host:port`.
`POSTGRES_PORT`	Port for hosts without an inline port (default `5432`).
`POSTGRES_USER`	Comma-separated user(s); a single value applies to every host.
`POSTGRES_PASSWORD`	Comma-separated password(s); a single value applies to every host.
`POSTGRES_DATABASE`	Comma-separated database names (default `postgres`).
`POSTGRES_SSLMODE`	Comma-separated sslmode (`disable`/`require`/`verify-ca`/`verify-full`).
`POSTGRES_NAME`	Comma-separated display names for the host switcher.
`CHM_ALLOW_PRIVATE_HOSTS`	Allow `localhost`/private addresses for local dev (ignored in Cloud).

Use a dedicated read-only Postgres role — chmonitor pins default_transaction_read_only=on on every query. Query Insights needs the pg_stat_statements extension; Running Queries only needs pg_stat_activity. See the Postgres feature guide for details.

Configure ClickHouse

Make sure the user you set in the previous step has the right grants:

Start the dev server

cd apps/dashboard
pnpm run dev

Open http://localhost:3000.

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

localhost connection refused — If ClickHouse is not running locally, update CLICKHOUSE_HOST to point at your remote instance.
Type errors on first run — Run pnpm run type-check from the repo root. Some generated types require a build pass first.
Missing system tables — See Enable system tables.