Environment Configuration Guide

Tracked templates:

• .env.example - local default reference.
• .env.local.example - copy to untracked .env for localhost and LAN work.
• .env.test.example - safe CI/test placeholder values.
• .env.staging.example - staging placeholders for https://staging-app.submicrons.net.

The app uses Better Auth. The actual runtime variables are BETTER_AUTH_SECRET and BETTER_AUTH_URL. AUTH_SECRET, AUTH_URL, and APP_URL are accepted as documented aliases for platform compatibility, but staging should keep the Better Auth names explicit.

Staging Required Variables

• APP_ENV=staging
• APP_URL=https://staging-app.submicrons.net
• DATABASE_URL
• AUTH_SECRET or BETTER_AUTH_SECRET
• AUTH_TRUST_HOST=true
• AUTH_URL, BETTER_AUTH_URL, or APP_URL
• LOG_LEVEL=info

External flags must stay disabled:

• COMMUNICATION_EXTERNAL_SENDING_ENABLED=false
• GOOGLE_DRIVE_SYNC_ENABLED=false
• WHATSAPP_SYNC_ENABLED=false
• GMAIL_SYNC_ENABLED=false
• WOOCOMMERCE_SYNC_ENABLED=false
• SOCIAL_SYNC_ENABLED=false
• PAYMENT_GATEWAY_ENABLED=false
• AI_AUTONOMOUS_ACTIONS_ENABLED=false

Run:

pnpm env:check
pnpm env:check:staging
node scripts/env-check.mjs staging --file=.env.staging

The committed staging template check allows placeholders. The real staging check should use the untracked values from the staging host or secret manager.

Sprint 24 Demo User Flags

Staging demo users are optional and must be created only with a temporary staging-only password:

SEED_STAGING_DEMO_USERS=true
SEED_STAGING_DEMO_PASSWORD=<temporary-12-plus-character-password>

Leave SEED_STAGING_DEMO_USERS=false until the staging database and demo credential handoff are approved. The environment check rejects missing, short, or placeholder demo passwords when the flag is enabled for real staging validation.