chmonitorConfiguration
How chmonitor reads configuration — sources, precedence, and links to the full reference for each category.
Read this first to understand how chmonitor loads settings and which category lives where. Then follow the links to each detailed reference.
How configuration works
chmonitor has three configuration sources. A later source always wins over an earlier one:
built-in defaults
→ CHM_CONFIG_FILE (TOML or YAML, feature permissions only)
→ environment variables| Source | What it controls | Notes |
|---|---|---|
| Built-in defaults | Everything | Every feature is public and enabled. Sensible query/pool timeouts. |
CHM_CONFIG_FILE | Feature permissions only | Optional file; mount at any path, point CHM_CONFIG_FILE at it. |
| Environment variables | All settings | Primary surface. Server vars take effect on restart; client vars require a rebuild. |
| Browser localStorage | Per-user UI state | Time range, alert settings, connection list. Not server config. |
One canonical name per setting
Settings the browser needs (auth provider, cloud mode, feature flags) are inlined
into the client bundle at build time as VITE_* vars. You set each one once:
use the canonical CHM_* name and vite.config.ts derives the matching VITE_*
for the client. For example, set CHM_AUTH_PROVIDER — not also
VITE_AUTH_PROVIDER.
Precedence per variable:
explicit VITE_* → canonical CHM_* → legacy NEXT_PUBLIC_* → built-in defaultSee Environment variables — one canonical name per setting.
Dual-surface settings need a rebuild
A dual-surface setting is needed at both build time (so vite inlines its
VITE_*) and runtime (so the server reads it). Changing it requires a rebuild
and redeploy — it is not a runtime-only change.
If you are migrating from a v0.2 Next.js deployment, the legacy NEXT_PUBLIC_*
prefix still works as a fallback.
Configuration categories
Each category has a full reference — expand for the essentials and the link.
Where to set variables
Use -e VAR=value flags on docker run, or environment: / an optional
env_file: .env in docker-compose.yml.
Set values in values.yaml → ConfigMap (non-secret) + Secret (secrets),
mounted via envFrom.
Non-secret vars via wrangler.toml [vars]; secrets via wrangler secret put.
Project → Settings → Environment Variables.
A .env / .env.local file or shell export (template:
apps/dashboard/.env.example).
The hosted product uses .env.production
On the hosted dash.chmonitor.dev, wrangler.toml declares no [vars] — the
non-secret config lives in committed apps/dashboard/.env.production (+
.env.preview), which feeds both the client build and the Worker runtime vars
(injected by scripts/patch-wrangler-env.ts at deploy). When working in this
repo, edit .env.production rather than re-adding a [vars] block.
See the per-platform install guides for copy-paste examples.
Config shape
The connection config chmonitor resolves at startup looks like this:
interface ChmonitorConfig {
host: string
user: string
password: string
maxExecutionTime?: number
}
const config: ChmonitorConfig = {
host: 'https://clickhouse.example.com:8443',
user: 'monitoring',
password: 'secret',
maxExecutionTime: 60,
}Related
Environment variables
Full list of every variable, grouped by category.
Settings
In-app settings and their server-side counterparts.
Connection presets
Create a least-privilege read-only ClickHouse user.
Feature permissions
Config-file and env-override details.
Authentication
Choose and configure an auth provider.
AI agent — configuration
LLM provider setup.
MCP server
Connect external AI tools.