Environment Variables Reference

For AI agents: All required variables must be set before starting the CMS API. Missing required variables will cause startup to fail with an explicit error message.

This page documents every environment variable and Cloudflare binding used by LumiBase.

Core runtime

The admin path is not configured by an environment variable. It is chosen during the Setup Wizard and stored in the database, so it can be rotated without a redeploy — and so it never sits in a build artifact.

It is private operational state. Do not expose it through VITE_* environment variables or client build metadata, and do not automatically redirect public/setup routes to it in production. See Private admin path.

First-run setup

With the flag on, every process that serves HTTP (LUMIBASE_PROCESS_ROLE web or all) mints the token as it starts, before it accepts requests, and prints it once:

[lumibase-cms] SETUP_TOKEN=<token>

Paste it into the setup wizard, or send it as setupToken to /setup/complete. Only its SHA-256 hash is stored, and the hash is cleared when setup completes.

A restart does not print a new token: the stored hash is kept so a token you already have stays valid, and the startup log says so instead. If you lost the line, clear the hash and restart — the next start prints a fresh token:

UPDATE lumibase_system_state SET setup_token_hash = NULL WHERE id = 'singleton';

Several replicas starting at once print exactly one token between them, so read it from whichever replica printed it.

Cloudflare Workers: not supported. A Worker has no process start to mint the token in, so with the flag on /setup/complete answers 503 SETUP_TOKEN_NOT_ISSUED with an explanation instead of accepting a token. Leave the flag unset there and complete setup right after deploying.

Encryption

"Before first use" means before anyone enrolls in 2FA or writes an encrypted field — not before boot. Without a key, enrollment fails closed with a 500 rather than a typed error.

Once seeds exist, a key can never be removed. TOTP seeds pin the key version that wrapped them and are not re-wrapped by the envelope migration, so retiring an old key locks those users out of their second factor. Rotation is also not a remedy for a leaked key. See Encryption key operations.

Authentication (Logto)

Database

For Cloudflare Workers, use the HYPERDRIVE binding (see Cloudflare Bindings).

Cache

Object storage

Search (MeiliSearch)

AI Copilot

Provider ↔ billing: nvidia and vertex call external clouds — NVIDIA and Google Cloud respectively — so their usage is not covered by AWS credit. nvidia (or a self-hosted NIM via NVIDIA_BASE_URL) and MeiliSearch are the pieces that pair naturally with AWS-hosted infrastructure.

Email (Resend)

SCIM provisioning

Pressure limiter (Docker / Node.js)

The Docker CMS process includes an overload guard for the Node.js event loop. When enabled and the process is saturated, API requests fail fast with HTTP 503, a SERVICE_UNAVAILABLE JSON envelope, Retry-After, and X-Lumi-Overload instead of queueing until the container becomes unresponsive. The guard bypasses /health and /metrics by default so operators can still inspect the instance.

Rate limiting

A fixed-window throttle guards the authenticated API. It keys per principal (user → API key → IP) and is scoped per site. When exceeded it returns HTTP 429 with a RATE_LIMITED envelope plus X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After. It fails open if the cache is unavailable, so it is defence-in-depth rather than a hard quota.

Large imports can trip the default budget. Raise LUMIBASE_RATE_LIMIT_MAX and prefer the bulk endpoint — see Data import.

GraphQL

Every GraphQL operation is validated before it runs against a depth limit and a static cost limit, rejecting abusively deep or wide queries at parse time (CWE-770). Depth is a compile-time constant (12); cost is tunable. Raise LUMIBASE_GQL_MAX_COST if a legitimate query is rejected. See graphql-api-spec.md.

Observability

Cloudflare Bindings

Configure these in apps/cms/wrangler.toml (not environment variables):

# wrangler.toml excerpt
[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id>"

[[kv_namespaces]]
binding = "CONFIG_CACHE"
id = "<your-kv-namespace-id>"

[[r2_buckets]]
binding = "MEDIA"
bucket_name = "lumibase-media"

[durable_objects]
bindings = [{ name = "SITE_ROOM", class_name = "SiteRoom" }]

Security checklist

Before deploying to production, verify:

• JWT_SECRET is at least 32 characters and stored as a Wrangler Secret or Docker secret
• LUMIBASE_DEV_AUTH is NOT set to true
• Database credentials are stored as secrets, not in .env files committed to git
• S3_SECRET_ACCESS_KEY is stored as a secret
• RESEND_API_KEY is stored as a secret
• CORS is configured to allow only your Studio and consumer domains