Skip to main content
All configuration is done through environment variables. Changes take effect only after restarting the affected service.
Copy .env.example from the repository root as a starting point — defaults are pre-configured for local development.

App

NEXT_PUBLIC_ENVIRONMENT

Runtime environment. Controls behavior such as logging verbosity and debug tooling. Allowed values: dev, prod — Default: dev

URLs

NEXT_PUBLIC_BUILDER_URL

Public-facing URL of the Builder service. Used by the browser to make API calls and by other services to construct absolute URLs. Required.

NEXT_PUBLIC_PARTYSOCKET_URL

Public-facing URL of the PartySocket WebSocket server. Used by the browser to establish realtime connections. Required.

NEXT_PUBLIC_ASSET_URL

Base URL for serving user-uploaded files and generated assets from storage. Should point to the public bucket prefix.

Authentication

BETTER_AUTH_SECRET

Secret key used to sign and verify authentication tokens. Generate with:
Required. Keep this secret — rotating it invalidates all existing sessions.

BETTER_AUTH_URL

Base URL of the authentication server. Must match NEXT_PUBLIC_BUILDER_URL in most deployments. Required.

Database

DATABASE_URL

PostgreSQL connection URL. Required. The database must be reachable from all three services (Builder, Worker).

Redis

REDIS_URL

Primary Redis connection URL. Used as the default for all Redis roles (cache, queue, pub/sub) unless overridden by the variables below. Required.

REDIS_CACHE_URL

Dedicated Redis instance for caching. Falls back to REDIS_URL when not set.

REDIS_QUEUE_URL

Dedicated Redis instance for BullMQ job queues. Falls back to REDIS_URL when not set.

REDIS_SEQUENCE_URL

Dedicated Redis instance for sequence scheduling. Falls back to REDIS_URL when not set.

S3-compatible storage

Compatible with AWS S3, RustFS, MinIO, Cloudflare R2, and any S3-compatible provider.

S3_ENDPOINT

S3 API endpoint URL. Required for non-AWS providers.

S3_ACCESS_KEY_ID

S3 access key ID.

S3_SECRET_ACCESS_KEY

S3 secret access key.

S3_REGION

S3 bucket region.

S3_BUCKET

S3 bucket name.

Email

SMTP_SERVER

SMTP connection URL for outgoing email. Required. Use smtp:// for plain/STARTTLS and smtps:// for implicit TLS. For local development, MailHog is included in the Docker Compose stack:

NEXT_PUBLIC_SMTP_FROM

Email address shown in the From field of outgoing messages. Required.

Realtime (PartySocket)

REALTIME_API_KEY

Shared secret used by the Builder and Worker to authenticate requests to the PartySocket service. Generate with:
Required. Must be the same value across all services.

Worker

SCHEDULER_BUCKET_RANGE

Hash bucket range this worker instance is responsible for in the sequence scheduler. For a single worker, use 0-255 (the full range). Split across replicas for horizontal scaling — e.g. 0-127 and 128-255 for two workers. Default: 0-255

Social Media keys

See the “channels” section of the documentation for the channel you want to configure, for details about how to set that up.