Environment Variables

This repo keeps variable-level env documentation in the tracked example files. Generated local .env files are intentionally compact so developers can edit values without scrolling through long comment blocks.

What This Covers

• Which files own env variable documentation.
• How bun run init and bun run env:refresh generate local env files.
• How to read production release vs local/non-release groups and subsystem subheadings.
• Which release boundaries matter for customer-cluster and Leverage-controlled secrets.

Fresh-Checkout Map

The first local setup uses three kinds of file:

File	First-run responsibility
Root .env	Docker’s Mongo username/password and Redis password
Root .env.common	Repeated local values such as the Auth database URL, Better Auth secret, and shared service keys
App .env files	App-owned values, including API DATABASE_URL/REDIS_URL and both CMS_*_DATABASE_URL values

Run bun run init to create missing files. Set root Docker credentials first, use those credentials in every local Mongo/Redis URL, and then run bun run env:refresh. Refresh copies filled shared values from .env.common into the matching app env files; it does not own or replace app-specific database URLs. Start Docker with bun run docker:up, then rerun bun run init to finish the database-backed setup. If a password contains URL-reserved characters, keep its raw value in the root .env and percent-encode it inside connection URLs.

If a value is missing, a setup command should name the exact env file and variable. Use that path; do not search or print every env file.

Source Of Truth

Use the matching example file for variable-level details, defaults, and safety notes:

Example file	Owns
.env.example	Repo-level local infrastructure, browser automation, and root test harness defaults
.env.common.example	Repeated local template inputs copied into app-local env files
apps/auth/.env.example	Better Auth runtime, web sign-in policy, workforce SSO, connector OAuth credentials
apps/api/.env.example	API runtime, connector storage/queues, retrieval, handoff, eval, and provider-test env
apps/cms-customer/.env.example	Customer CMS runtime and customer-cluster governance config
apps/cms-leverage/.env.example	Leverage-owned CMS runtime and internal assistant-feedback review handoff config
apps/web/.env.example	Browser-facing web runtime config
apps/web-token-replacer/.env.example	Local token replacer shell config
apps/meltano/.env.example	Meltano connector runtime and manual tap debugging config

Support-dev explains how the files fit together. It should not duplicate every variable description, because copied env tables drift quickly.

Finding Release Env For Helm And Kubernetes

When you are building or reviewing Kubernetes manifests, Helm values, external-secret definitions, or deployment runbooks, start from the example-file headings instead of scanning every local default.

Use this release packaging path:

1. Open the example file for the app you are packaging.
2. Include variables under Customer-Cluster Production Release, Leverage-Controlled Production Release, and Production Release when they apply to that deployed app.
3. Use # --- ... --- subheadings to map variables to Helm ConfigMaps, Secrets, runtime config files, service URLs, storage, queues, handoff wiring, or other subsystem-specific manifests.
4. Exclude Local / Non-Release from release manifests by default. Include setup/maintenance subgroups only for explicit jobs or runbooks, not normal pod runtime env.
5. Cross-check customer-cluster charts under infra/helm/customer-cluster/ before adding env values, Secret mounts, service accounts, RBAC, or external-secret wiring.

Customer-cluster packages should normally consult:

Release surface	Primary env examples	Helm/Kubernetes surface
Customer API	apps/api/.env.example heading Customer-Cluster Production Release and its subsystem subheadings	infra/helm/customer-cluster/templates/api-deployment.yaml, infra/helm/customer-cluster/templates/api-runtime-configmap.yaml, infra/helm/customer-cluster/values.yaml
Customer CMS	apps/cms-customer/.env.example heading Customer-Cluster Production Release	infra/helm/customer-cluster/templates/cms-customer-deployment.yaml, infra/helm/customer-cluster/templates/cms-customer-rbac.yaml, infra/helm/customer-cluster/values.yaml
Connector credential slots	apps/api/.env.example, apps/cms-customer/.env.example Credential Stores subheadings	infra/helm/customer-cluster/templates/connector-credentials-secret.yaml, infra/helm/customer-cluster/templates/public-provider-credentials-secret.yaml
Leverage-owned CMS	apps/cms-leverage/.env.example heading Leverage-Controlled Production Release	Not installed into customer clusters

If a release needs a value that is only documented under Local / Non-Release, stop and reclassify the owning example file first. That usually means the variable is either in the wrong section or the release design needs a separate approval.

Generated Local Files

bun run init creates missing local env files from tracked examples. It creates .env.common first, then creates missing app/root .env files. Matching keys from .env.common are copied into each new app-local target.

bun run env:refresh rewrites local env files from their examples, backs up existing files in place, and carries forward matching existing values. The generated files contain only:

• a short generated-file notice
• key/value assignment lines
• blank separators

Read the matching .env.example or .env.common.example when you need comments, category labels, examples, or security notes.

Category Headings

Example files use top-level section headings to answer whether a variable belongs in release packaging by default:

Top-level heading	Meaning
Production Release	Normal deployment/runtime config for the owning app or service
Customer-Cluster Production Release	Runtime config that can belong in customer-controlled deployments
Leverage-Controlled Production Release	Runtime config for Leverage-owned infrastructure only; never install into customer clusters
Local / Non-Release	Developer-machine defaults, test/eval harnesses, local debug switches, template inputs, and setup/maintenance values that are not normal pod runtime env

The heading classifies the variables below it until the next heading.

Subheadings such as # --- Connector Credential Stores ---, # --- Email Delivery ---, # --- Tests And Evals ---, or # --- Setup And Maintenance --- preserve code-use grouping inside the top-level classification. Subheadings do not override the top-level release/local classification.

Release Boundaries

Customer-cluster release env belongs only to customer-installed components. Do not put Leverage-owned Jira credentials, central service tokens, Leverage databases, or internal-only Leverage secrets into customer Helm values, Kubernetes manifests, external secret stores, images, or app config.

Leverage-controlled env belongs only to Leverage-owned infrastructure. cms-leverage env uses CMS_LEVERAGE_* names and must stay separate from cms-customer env, customer Better Auth accounts, customer CMS accounts, and customer-cluster release bundles.

Browser-facing apps must not receive service API keys. apps/web/.env.example and apps/web-token-replacer/.env.example intentionally document frontend-safe variables only.

Changing Env Vars

When adding, changing, or removing an env variable:

1. Update the owning .env.example in the same change.
2. Put the variable under the correct top-level release/local heading and subsystem subheading.
3. If the same local value should be edited once and copied to app-local env files, add or update the matching entry in .env.common.example.
4. Keep .env.common.example comments and defaults aligned with the owning app example.
5. Do not add compatibility aliases or old env names in this pre-release repo unless explicitly requested by a human.
6. Update this page only when the env model, category meanings, or file ownership changes.

After example changes, run:

bun run env:refresh

Then restart the affected local dev processes so they read the updated app-local .env files.

Canonical Sources

• .env.example
• .env.common.example
• scripts/envFiles.ts
• scripts/envFiles.test.ts
• infra/helm/customer-cluster/
• apps/auth/.env.example
• apps/api/.env.example
• apps/cms-customer/.env.example
• apps/cms-leverage/.env.example
• apps/web/.env.example
• apps/web-token-replacer/.env.example
• apps/meltano/.env.example