# Migrate to v0.3

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

1. Pull the new image tag:

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

2. Stop and remove the old container:

   ```bash
   docker stop chmonitor && docker rm chmonitor
   ```

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

   ```bash
   # 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:

   ```bash
   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`:

   ```yaml
   image:
     tag: v0.3.0
   ```

2. Rename browser env vars (optional):

   ```yaml
   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:

   ```bash
   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:

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

3. Deploy:

   ```bash
   bun run cf:deploy
   ```

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

   ```bash
   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:

   ```bash
   git pull origin main
   git checkout v0.3.0
   ```

2. Install dependencies:

   ```bash
   bun install
   ```

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

   ```bash
   # .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:

   ```bash
   bun run build
   bun run start
   ```

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

```text
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:

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:

| 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](/reference/environment-variables) for the full list.

---

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