Environment

This is the canonical Lucent environment reference.

Use it as the single source of truth for:

what is required vs optional
what belongs to Lucent core vs optional integrations
which values are acceptable only for local development

Required For Most Apps

These are the variables most Lucent apps need in production.

Variable	Required When	Notes
`DATABASE_URL`	Always for `db.adapter: "postgres"`	PostgreSQL connection string
`JWT_SECRET`	JWT auth is enabled	Must be at least 32 characters
`SESSION_SECRET`	Session auth is enabled	Must be at least 32 characters

Optional By Feature

Only set these when the corresponding feature is enabled.

Redis / Cache

Variable	Required When	Notes
`REDIS_URL`	Using response cache	Example: `redis://localhost:6379`

Queues

Variable	Required When	Notes
`REDIS_URL`	Using `LucentQueueManager`	Example: `redis://localhost:6379`

SMTP Email

Variable	Required When	Notes
`SMTP_HOST`	Using SMTP email provider	SMTP server hostname
`SMTP_PORT`	Using SMTP email provider	Optional, defaults to `587` in most setups
`SMTP_SECURE`	Using SMTP email provider	Optional, use `true` for port `465`
`SMTP_USER`	Using SMTP email provider	SMTP username
`SMTP_PASS`	Using SMTP email provider	SMTP password
`SMTP_FROM`	Sending email	Fallback sender address

Resend Email

Variable	Required When	Notes
`RESEND_API_KEY`	Using Resend provider	API key for Resend
`SMTP_FROM`	Sending email	Still used as the default `from` address

S3 Storage

Variable	Required When	Notes
`S3_BUCKET`	Using `storage.provider: "s3"`	Bucket name
`S3_REGION`	Using `storage.provider: "s3"`	Region name
`AWS_ACCESS_KEY_ID`	Using `storage.provider: "s3"`	Access key
`AWS_SECRET_ACCESS_KEY`	Using `storage.provider: "s3"`	Secret key

Google Drive Storage

Variable	Required When	Notes
`GOOGLE_DRIVE_CLIENT_EMAIL`	Using `upload.provider: "googleDrive"`	Service account email
`GOOGLE_DRIVE_PRIVATE_KEY`	Using `upload.provider: "googleDrive"`	Service account private key
`GOOGLE_DRIVE_FOLDER_ID`	Using `upload.provider: "googleDrive"`	Shared drive folder ID or URL

Google Drive service-account uploads require a Google Workspace Shared drive folder, or domain-wide delegation to a Workspace user with Drive storage quota. A normal My Drive folder shared with the service account is not sufficient for uploads.

Secrets

Variable	Required When	Notes
`LUCENT_SECRETS_KEY`	Using `secrets.enabled: true`	32-byte master key generated by `LucentSecrets.generateMasterKey()`

SurrealDB

Variable	Required When	Notes
`SURREAL_URL`	Using `db.adapter: "surrealdb"`	Example: `ws://localhost:8000`
`SURREAL_NAMESPACE`	Optional for SurrealDB	If not passed in config
`SURREAL_DATABASE`	Optional for SurrealDB	If not passed in config
`SURREAL_USERNAME`	Optional for SurrealDB auth	If auth is enabled
`SURREAL_PASSWORD`	Optional for SurrealDB auth	If auth is enabled

App-Level Convenience Variables

Lucent does not require these, but many apps use them.

Variable	Purpose
`PORT`	Bun server port
`NODE_ENV`	Standard runtime mode
`COOKIE_DOMAIN`	Shared cookie domain for JWT/session cookie setups
`VERIFY_EMAIL_URL`	Base URL for verification links

Local Development Example

DATABASE_URL=postgresql://postgres:password@localhost:5432/lucent_example
JWT_SECRET=dev-secret-change-before-production-123
SESSION_SECRET=dev-session-secret-change-before-prod-123
PORT=3000
NODE_ENV=development

If you use optional features, extend that with:

REDIS_URL=redis://localhost:6379
SMTP_HOST=smtp.example.com
SMTP_USER=user
SMTP_PASS=pass
SMTP_FROM="My App <noreply@example.com>"
RESEND_API_KEY=re_xxx
S3_BUCKET=my-bucket
S3_REGION=us-east-1
AWS_ACCESS_KEY_ID=xxx
AWS_SECRET_ACCESS_KEY=xxx

Production Rules

Never rely on development fallback secrets in production
Do not use wildcard CORS with credentials enabled
Ensure Redis durability and high availability for BullMQ jobs that must survive restarts
Treat email and storage credentials as required only when those integrations are enabled
Keep app-level variables such as PORT and reverse proxy config outside Lucent-specific docs where possible