Configuration

CHOps is configured through a .env file in the project root. It holds your CHOps login credentials, the session secret, the server port, optional email settings, and a few frontend build values. Your ClickHouse® connection details do not go here.

Create your file by a copy of the shipped example, then edit it:

cp .env.example .env

What about ClickHouse® connection details? Those are configured in the browser, not in this file. After you log in, go to Administration > Cluster Management to add your ClickHouse® nodes. Their passwords are encrypted and stored in CHOps's database, not in .env.

How CHOps reads configuration

Two things are worth knowing before you edit anything.

Backend variables are read at startup. On boot, the server validates its environment and exits at once if a required value is missing, so a typo in a required variable stops CHOps from a start, rather than a subtle failure later. To change a backend variable takes effect on the next restart.

Frontend variables (the VITE_ ones) are baked in at build time. Vite reads them when you run bun run build (or bun run dev) and compiles their values into the frontend bundle. To change a VITE_ value means a rebuild of the frontend for it to take effect. To change it on an already-built server does nothing.

Super admins (required)

These are the login accounts for CHOps itself, not your ClickHouse® users. At least the first super admin must be fully defined, and you can define up to three. Each account needs a username, a password, and an email address. The email is required: the server will not start if SUPER_ADMIN_1_EMAIL is missing.

These accounts are seeded into CHOps's database on first startup, then used for initial setup and emergency login.

Example:

SUPER_ADMIN_1=admin
SUPER_ADMIN_1_PASSWORD=MySecurePassword123
SUPER_ADMIN_1_EMAIL=admin@example.com

You define a second and third admin by a fill of all three of their numbered variables. A partially filled set (for example, a username with no email) is ignored.

Legacy single-admin format

Older installations used an unnumbered set. It is still accepted when the numbered variables are absent:

SUPER_ADMIN=admin
SUPER_ADMIN_PASSWORD=change_me
SUPER_ADMIN_EMAIL=admin@example.com

New installations should use the numbered SUPER_ADMIN_1 form above.

Session and authentication (required)

Never change ENCRYPTION_SECRET after your first run. It makes the key for every stored password, so a new value makes them unreadable and they cannot be recovered. You would have to enter every one again.

Upgrading? This was called SESSION_SECRET. Rename it in your .env file and keep the same value. CHOps refuses to start until you rename it, and the message says what to do.

Login tokens no longer use this value. CHOps makes its own signing keys and changes them daily, so there is nothing to set for them.

Server

Login fallback

The shipped .env.example sets DISABLE_ENV_LOGIN=true. This is safe from the start, because your first super admin is also seeded into the CHOps database on first startup and can log in through the normal database path. Leave it at true to keep the surface small, or set it to false (or remove it) if you want the .env credentials to work as a fallback during setup. Any value other than the exact string true leaves the fallback enabled.

Email (SMTP, optional)

Configure SMTP only if you want CHOps to send email. When configured, it is used for alert notifications, to email a generated password to a newly created user, and for password-reset messages. Without these values, those emails are simply not sent.

Password-reset link

Build and version metadata (optional)

These describe the running build and are normally populated by the build pipeline. In local development they are usually left blank. The canonical version of record lives in version.json at the project root, and the /api/version endpoint and the startup log surface these values.

Frontend build variables

The frontend reads these at build time and compiles them into the bundle. They must be present when you build, and a change to them needs a rebuild.

These variables have safe defaults compiled into the code, so you do not need to set them. Set one only if you want to change the local-storage key it controls.

The connection bar

At the top of the app, a connection bar controls which ClickHouse® node the pages talk to. It lists your configured nodes. To select one loads that node's saved credentials, and the connection status indicator shows whether CHOps can currently reach it. This is separate from the SQL Editor and Schema Studio, which connect with each user's own ClickHouse® credentials, entered at connect time.

Dark mode and light mode

Click the sun or moon icon in the top-right corner to switch themes. CHOps saves your preference in your browser.

Date and time format

All dates and times in CHOps use the 24-hour format, for example 2026-05-13 14:30:00, which matches the format ClickHouse® expects.

Settings that moved into the interface

Fifteen settings that were once environment variables are now on the Administration > App Config page. You change them there, and they apply at once with no restart.

The variables still work. CHOps uses them when nothing is set on the page, so an existing deployment needs no change.

Eight more settings on that page were never environment variables. They were fixed values in the code: the lockout rules, the session length, and the four Kubernetes timings.

These did not move, and are still set on the server only: