Environments

Topology

Every app has a stable role key in code and a DNS label that depends on the environment. Staging uses the fixed cenvora.dev base; production uses ROOT_DOMAIN, and development uses localhost. The mapping lives in packages/env/src/hosts.ts and is the only place it is defined; apps call hosts(), originFor(), or read publicHosts / serverHosts rather than building URLs by hand.

Production uses APP_ENV=production, PROJECT_NAME=lee-kong-si, and ROOT_DOMAIN=cenvora.dev; this deliberately resolves to the six project-scoped Cenvora hosts shown above. Staging uses APP_ENV=staging, PROJECT_NAME=lee-kong-si-test, and the same fixed cenvora.dev base. The six current purpose labels are www, app, docs, platform, partner, and api. A custom non-Cenvora production root uses admin for the platform host; the project-scoped Cenvora convention uses platform in both environments. Future approved purposes such as merchant or user are not current apps or HostRole values.

With PROJECT_NAME=lee-kong-si-test and ROOT_DOMAIN=cenvora.dev, staging yields app.lee-kong-si-test.cenvora.dev. The production Cenvora convention similarly yields app.lee-kong-si.cenvora.dev; a separately owned production registrable domain can still be provided through ROOT_DOMAIN when approved. The staging base is fixed to cenvora.dev. Print the resolved table at any time with:

bun run vigor hosts --env staging
bun run vigor hosts --env production --json

The session cookie domain is .<project>.cenvora.dev in staging, .<ROOT_DOMAIN> in production, and unset on localhost. This lets one login work across the sibling services of the same project. See Authentication.

Other staging projects do not receive that project-domain cookie. This narrower cookie scope is not full security isolation: all projects remain same-site under the shared registrable cenvora.dev domain, and cookie-tossing risks remain. Trust every sibling service within one project, and place mutually untrusted projects on separate registrable domains.

Environment variables

The root .env.example lists every variable. Server-side variables are validated by @vigor/env/server (serverEnv); browser-safe variables carry the NEXT_PUBLIC_ prefix and are validated by @vigor/env/next (nextEnv). The API requires its server configuration at boot. Next.js site builds only need their browser-safe topology and integration variables.

Topology

Data and auth

Email

Error logs

ROOTPRINT_URL and ROOTPRINT_INGEST_KEY are a pair: leaving both blank disables server delivery; setting only one is invalid. Browser code never receives the ingest key.

Feature flags

AI and client communication

Misc

Per-environment checklist

• Development: copy .env.example to .env, generate BETTER_AUTH_SECRET, keep both Rootprint server values blank, and keep NEXT_PUBLIC_ROOTPRINT_ENABLED=false.
• Staging: set APP_ENV=staging and NEXT_PUBLIC_APP_ENV=staging, match PROJECT_NAME and NEXT_PUBLIC_PROJECT_NAME, and use cenvora.dev for both root-domain variables unless retaining a production domain for canonical metadata. Host generation always uses cenvora.dev for staging. Use a unique BETTER_AUTH_SECRET and, when approved, the staging Rootprint URL/key pair and GrowthBook client key. Browser reporting remains opt-in.
• Production: set both app-environment variables to production and both root-domain variables to the project's production domain. Generate different auth and ingest secrets; staging and production must never share them or their data stores.