Environment Strategy
Structure env files, flags, and service availability across local, staging, and production.
This project is env-driven: branding, feature rollout, external service behavior, and billing enforcement all depend on environment variables.
Use DEVELOPMENT_MODE=true, enable only services under active test, and keep bootstrap simple.
Mirror production topology as closely as possible; validate real toggles with test billing/providers.
Use strong secrets, strict service/toggle alignment, and FEATURE_BILLING_ENFORCEMENT_ENABLED=true.
1) File Layout and Ownership
Use .env.example as the source template, then copy into each app:
cp .env.example apps/app/.env
cp .env.example apps/admin/.env
cp .env.example apps/web/.envEach app resolves env at its own runtime/build context.
2) Variable Tiers
Required core
Set these in all real environments:
DATABASE_URLBETTER_AUTH_SECRETBETTER_AUTH_URLAPP_URLWEBSITE_URL- one AI provider key (
GROQ_API_KEY,OPENAI_API_KEY, orGOOGLE_GENERATIVE_AI_API_KEY)
Infrastructure
Match values to your deployed services:
- Postgres/Redis/MinIO creds and ports
S3_ENDPOINT,S3_PUBLIC_ENDPOINT,S3_ACCESS_KEY,S3_SECRET_KEY,S3_BUCKET- optional memory/search services (
QDRANT_*,NEO4J_*,SEARXNG_URL)
Feature and service toggles
Feature flags:
FEATURE_SEARCH_ENABLEDFEATURE_DEEP_SEARCH_ENABLEDFEATURE_MEMORY_ENABLEDFEATURE_ARTIFACTS_ENABLEDFEATURE_TRANSCRIPTION_ENABLEDFEATURE_DOCUMENT_COMPARISON_ENABLEDFEATURE_BILLING_ENFORCEMENT_ENABLEDFEATURE_ANALYTICS_ENABLED
Service availability flags:
SERVICE_SEARXNG_AVAILABLESERVICE_BROWSERUSE_AVAILABLESERVICE_QDRANT_AVAILABLESERVICE_NEO4J_AVAILABLESERVICE_REDIS_AVAILABLE
3) Environment Profiles
Local development
DEVELOPMENT_MODE=true- optionally disable heavy features not under test
- use MailDev + local Docker services
Staging / pre-production
DEVELOPMENT_MODE=false- billing enforcement can be true with test Stripe keys
- match production topology closely
Production
DEVELOPMENT_MODE=falseFEATURE_BILLING_ENFORCEMENT_ENABLED=true- real domains and TLS endpoints
- strong secrets and no default credentials
4) Rollout Pattern
- Deploy service first (for example Qdrant or SearXNG).
- Mark service availability true.
- Enable feature flag.
- Observe logs and usage.
- Roll back by flipping feature flag to false if needed.
5) Quick Validation Commands
bun health
bun typecheck
bun build
docker compose psFor production stack mode:
docker stack services ai
docker stack ps ai