chmonitor — ClickHouse Monitoring Dashboard

Upgrade chmonitor from v0.2 (Next.js) to v0.3 (TanStack Start) — platform steps and the VITE_* variable rename.

v0.3 rebuilds the dashboard on TanStack Start. Features, routes, and ClickHouse setup are unchanged. Browser-exposed environment variables now standardize on the VITE_* prefix, with NEXT_PUBLIC_* kept as a compatibility fallback. For most deployments, the upgrade is a redeploy plus an optional rename.

What changed

Browser variable prefix: `NEXT_PUBLIC_` → `VITE_`

Variables exposed to the browser now use the VITE_ prefix. Server-side and secret variables (CLICKHOUSE_*, CHM_*, LLM_*, CLERK_SECRET_KEY, etc.) are unchanged.

Old name	New name
`NEXT_PUBLIC_AUTH_PROVIDER`	`VITE_AUTH_PROVIDER`
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	`VITE_CLERK_PUBLISHABLE_KEY`
`NEXT_PUBLIC_FEATURE_CONVERSATION_DB`	`VITE_FEATURE_CONVERSATION_DB`
`NEXT_PUBLIC_AUTOCOMPLETE_LIMIT`	`VITE_AUTOCOMPLETE_LIMIT`
`NEXT_PUBLIC_RUNNING_QUERIES_REFRESH_MS`	`VITE_RUNNING_QUERIES_REFRESH_MS`

The rename is optional

The old NEXT_PUBLIC_* names still work as a fallback. The rename is recommended but not required — nothing breaks if you skip it.

Browser variables are build-time only

Browser variables must be set at build time (in your CI build step or build config), not only as runtime environment variables.

Upgrade steps by platform

Pull the new image

docker pull ghcr.io/chmonitor/chmonitor:v0.3.0

Stop and remove the old container

docker stop chmonitor && docker rm chmonitor

Rename browser env vars (optional but recommended)

-e NEXT_PUBLIC_AUTH_PROVIDER=clerk \
-e NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_... \

# After
-e VITE_AUTH_PROVIDER=clerk \
-e VITE_CLERK_PUBLISHABLE_KEY=pk_live_... \

Start with the v0.3 image

docker run -d \
  -e CLICKHOUSE_HOST='http://clickhouse:8123' \
  -e CLICKHOUSE_USER='default' \
  -e CLICKHOUSE_PASSWORD='' \
  -e VITE_AUTH_PROVIDER=clerk \
  -e VITE_CLERK_PUBLISHABLE_KEY=pk_live_... \
  -e CLERK_SECRET_KEY=sk_live_... \
  -p 3000:3000 \
  --name chmonitor \
  ghcr.io/chmonitor/chmonitor:v0.3.0

Verify

Open the dashboard and verify Overview loads with live data.

Update the image tag in your `values.yaml`

image:
  tag: v0.3.0

Rename browser env vars (optional)

env:
  # Before
  - name: NEXT_PUBLIC_AUTH_PROVIDER
    value: clerk
  # After
  - name: VITE_AUTH_PROVIDER
    value: clerk

If you store NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY in a Secret, rename the key there too.

Apply and roll out

helm upgrade chmonitor chmonitor/chmonitor -f values.yaml
kubectl rollout status deployment/chmonitor

Verify

Verify Overview loads with live data.

Browser variables must be present at build time. Set them in your CI environment (GitHub Actions secrets or Cloudflare dashboard) before running the build.

Update the build to reference the new image or branch

Rename browser vars in CI or Cloudflare Pages build config

# GitHub Actions — add to your workflow env or secrets
VITE_AUTH_PROVIDER=clerk
VITE_CLERK_PUBLISHABLE_KEY=${{ secrets.CLERK_PUBLISHABLE_KEY }}

Deploy

bun run cf:deploy

Add any new v0.3 secrets (if using new features)

wrangler secret put CHM_API_KEY_SECRET
wrangler secret put HEALTH_ALERT_WEBHOOK_URL

Verify

Verify the deployed URL loads correctly.

Update environment variables

In Vercel project → Settings → Environment Variables:

Add VITE_AUTH_PROVIDER (replaces NEXT_PUBLIC_AUTH_PROVIDER)
Add VITE_CLERK_PUBLISHABLE_KEY (replaces NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY)
Keep old NEXT_PUBLIC_* names if you want backward compatibility (both work)

Trigger a redeploy

Deployments → Redeploy, or push a new commit.

Verify

Verify Overview loads.

Pull the latest source

git pull origin main
git checkout v0.3.0

Install dependencies

bun install

Update your `.env` file

# .env
VITE_AUTH_PROVIDER=clerk
VITE_CLERK_PUBLISHABLE_KEY=pk_live_...
# Server vars unchanged:
CLERK_SECRET_KEY=sk_live_...
CLICKHOUSE_HOST=http://localhost:8123

Rebuild and restart

bun run build
bun run start

Verify

Verify Overview loads with live data.

Automate it with an AI assistant

Don't want to hand-edit env files? Paste your current configuration (.env, docker-compose.yml, Helm values.yaml, or a k8s manifest) into any AI assistant together with the prompt below. It applies the v0.3 rename rules and returns the migrated config plus a summary of what changed.

You are migrating a chmonitor deployment from v0.2 (Next.js) to v0.3 (TanStack Start).
Here is my current environment (.env / docker-compose / wrangler / k8s manifest):

<PASTE YOUR ENV HERE>

Rewrite it for v0.3 applying EXACTLY these rules, and output the migrated config
plus a short list of what you changed:

1. Rename every client var prefix NEXT_PUBLIC_ -> VITE_. Specifically:
   NEXT_PUBLIC_AUTH_PROVIDER          -> VITE_AUTH_PROVIDER
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY  -> VITE_CLERK_PUBLISHABLE_KEY
   NEXT_PUBLIC_FEATURE_CONVERSATION_DB-> VITE_FEATURE_CONVERSATION_DB
   NEXT_PUBLIC_AUTOCOMPLETE_LIMIT     -> VITE_AUTOCOMPLETE_LIMIT
   NEXT_PUBLIC_RUNNING_QUERIES_REFRESH_MS -> VITE_RUNNING_QUERIES_REFRESH_MS
   (any other NEXT_PUBLIC_X -> VITE_X). The old names still work as a fallback,
   so keep them if backward compatibility matters; otherwise prefer the new names.
2. Add server-side auth var CHM_AUTH_PROVIDER (none|clerk|proxy) mirroring the
   client provider. It is authoritative on the server; keep VITE_AUTH_PROVIDER too
   so the browser bundle agrees.
3. Do NOT rename server vars: CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD,
   CLICKHOUSE_NAME, CLICKHOUSE_MAX_EXECUTION_TIME, CLERK_SECRET_KEY, *_API_KEY — keep as-is.
4. VITE_* vars are build-time inlined: ensure they are present at image/Worker BUILD
   time (Docker build-args or CI build env), not only at container runtime.
5. If this is a Docker deployment, change the container start command from
   `node server.js` to `node server/index.mjs`. Port 3000 and the /api/healthz
   healthcheck are unchanged.
6. Flag anything that has no v0.3 equivalent instead of silently dropping it.

Kept in sync with the release notes

This same prompt is published in the v0.3 GitHub release notes, kept in sync from .github/release-migration-prompt.md.

Variable	Feature
`CHM_API_KEY_SECRET`	API key auth layer (MCP, scripts)
`CHM_AUTH_PROVIDER`	Pluggable auth (replaces Clerk-only)
`CHM_CF_ACCESS_TEAM_DOMAIN` + `CHM_CF_ACCESS_AUD`	Cloudflare Access proxy auth
`CHM_PROXY_AUTH_SECRET`	Trusted-header proxy auth
`HEALTH_ALERT_ENABLED` + `HEALTH_ALERT_WEBHOOK_URL`	Health alerting cron sweep
`VITE_FEATURE_CONVERSATION_DB` (build-time) + `CONVERSATION_STORE_BACKEND` (runtime)	Server-side conversation history

See Environment Variables for the full list.

ClickHouse setup carries over

ClickHouse hosts, credentials, and feature permissions carry over unchanged. No ClickHouse schema changes are required.

Migrate to v0.3

What changed

Browser variable prefix: `NEXT_PUBLIC_` → `VITE_`

Upgrade steps by platform

Pull the new image

Stop and remove the old container

Rename browser env vars (optional but recommended)

Start with the v0.3 image

Verify

Update the image tag in your `values.yaml`

Rename browser env vars (optional)

Apply and roll out

Verify

Update the build to reference the new image or branch

Rename browser vars in CI or Cloudflare Pages build config

Deploy

Add any new v0.3 secrets (if using new features)

Verify

Update environment variables

Trigger a redeploy

Verify

Pull the latest source

Install dependencies

Update your `.env` file

Rebuild and restart

Verify

Automate it with an AI assistant

Verify

Load the dashboard

Confirm authentication

Test the AI agent

Check the build

New variables in v0.3

v0.3 — What's New

Environment variables

Authentication

On this page