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.

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

1. Pull the new image tag:

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

2. Stop and remove the old container:

   docker stop chmonitor && docker rm chmonitor

3. 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_... \

4. 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

5. Open the dashboard and verify Overview loads with live data.

Kubernetes / Helm

1. Update the image tag in your values.yaml:

   image:
     tag: v0.3.0

2. 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.

3. Apply and roll out:

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

4. 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.

1. Update the build to reference the new image or branch.

2. 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 }}

3. Deploy:

   bun run cf:deploy

4. If you use new v0.3 features (conversation persistence, health alerting), add any new secrets:

   wrangler secret put CHM_API_KEY_SECRET
   wrangler secret put HEALTH_ALERT_WEBHOOK_URL

5. Verify the deployed URL loads correctly.

Vercel

1. 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)

2. Trigger a redeploy (Deployments → Redeploy, or push a new commit).

3. Verify Overview loads.

Self-hosted (Node / bare metal)

1. Pull the latest source:

   git pull origin main
   git checkout v0.3.0

2. Install dependencies:

   bun install

3. Update your .env file — rename browser vars:

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

4. Rebuild and restart:

   bun run build
   bun run start

5. Verify Overview loads with live data.

Verify

After upgrading on any platform:

1. Open the dashboard — Overview should render charts with live data.
2. If authentication is enabled, sign in and confirm data loads.
3. If the AI agent is configured, open /agents and send a message.
4. 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:

See Environment Variables for the full list.

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