Migrate to v0.3

Open as Markdown

v0.3 introduces a migration update. The dashboard is rebuilt on TanStack Start. Features, routes, and ClickHouse setup are unchanged. Browser-exposed environment variables are now standardized on the VITE_* prefix, with NEXT_PUBLIC_* kept as a compatibility fallback.

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 old NEXT_PUBLIC_* names still work as a fallback. The rename is recommended but not required — nothing breaks if you skip it.

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

Docker

Pull the new image tag:

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

Stop and remove the old container:

docker stop chmonitor && docker rm chmonitor

Rename browser env vars in your run command (optional but recommended):

# Before
-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 a new container 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/duyet/chmonitor:v0.3.0

Open the dashboard and verify Overview loads with live data.

Kubernetes / Helm

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 duyet/clickhouse-monitoring -f values.yaml
kubectl rollout status deployment/chmonitor

Verify Overview loads with live data.

Cloudflare Workers

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.

In your CI or Cloudflare Pages build config, rename the browser vars:

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

Deploy:
Terminal window
```
bun run cf:deploy
```
If you use new v0.3 features (conversation persistence, health alerting), add any new secrets:
Terminal window
```
wrangler secret put CHM_API_KEY_SECRET
wrangler secret put HEALTH_ALERT_WEBHOOK_URL
```
Verify the deployed URL loads correctly.

Vercel

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 Overview loads.

Self-hosted (Node / bare metal)

Pull the latest source:
Terminal window
```
git pull origin main
git checkout v0.3.0
```
Install dependencies:
Terminal window
```
bun install
```

Update your .env file — rename browser vars:

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:
Terminal window
```
bun run build
bun run start
```
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.

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

Verify

After upgrading on any platform:

Open the dashboard — Overview should render charts with live data.
If authentication is enabled, sign in and confirm data loads.
If the AI agent is configured, open /agents and send a message.
Check /about — the build timestamp and version should reflect the new release.

New variables in v0.3

v0.3 adds optional new configuration. None is required for the upgrade — set these only if you want the new features:

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 hosts, credentials, and feature permissions carry over unchanged. No ClickHouse schema changes are required.