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

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

​
URLs

​
NEXT_PUBLIC_BUILDER_URL

NEXT_PUBLIC_BUILDER_URL=https://builder.yourdomain.com
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

NEXT_PUBLIC_PARTYSOCKET_URL=https://ws.yourdomain.com
Public-facing URL of the PartySocket WebSocket server. Used by the browser to establish realtime connections. Required.

​
NEXT_PUBLIC_ASSET_URL

NEXT_PUBLIC_ASSET_URL=https://cdn.yourdomain.com/chatbotx/
Base URL for serving user-uploaded files and generated assets from storage. Should point to the public bucket prefix.

​
Authentication

​
BETTER_AUTH_SECRET

BETTER_AUTH_SECRET=your-secret-here
Secret key used to sign and verify authentication tokens. Generate with: 
openssl rand -base64 32
Required. Keep this secret — rotating it invalidates all existing sessions.

​
BETTER_AUTH_URL

BETTER_AUTH_URL=https://builder.yourdomain.com
Base URL of the authentication server. Must match NEXT_PUBLIC_BUILDER_URL in most deployments. Required.

​
Database

​
DATABASE_URL

DATABASE_URL=postgresql://user:password@localhost:5432/chatbotx?schema=public
PostgreSQL connection URL. Required. The database must be reachable from all three services (Builder, Worker).

​
Redis

​
REDIS_URL

REDIS_URL=redis://localhost:6379
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

REDIS_CACHE_URL=redis://localhost:6380
Dedicated Redis instance for caching. Falls back to REDIS_URL when not set.

​
REDIS_QUEUE_URL

REDIS_QUEUE_URL=redis://localhost:6381
Dedicated Redis instance for BullMQ job queues. Falls back to REDIS_URL when not set.

​
REDIS_SEQUENCE_URL

REDIS_SEQUENCE_URL=redis://localhost:6382
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_ENDPOINT=https://s3.amazonaws.com
# or for self-hosted:
S3_ENDPOINT=http://localhost:9000
S3 API endpoint URL. Required for non-AWS providers.

​
S3_ACCESS_KEY_ID

S3_ACCESS_KEY_ID=your-access-key
S3 access key ID.

​
S3_SECRET_ACCESS_KEY

S3_SECRET_ACCESS_KEY=your-secret-key
S3 secret access key.

​
S3_REGION

S3_REGION=us-east-1
S3 bucket region.

​
S3_BUCKET

S3_BUCKET=chatbotx
S3 bucket name.

​
Email

​
SMTP_SERVER

SMTP_SERVER=smtp://username:password@smtp.yourdomain.com:587
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: 
SMTP_SERVER=smtp://localhost:1025

​
NEXT_PUBLIC_SMTP_FROM

NEXT_PUBLIC_SMTP_FROM=no-reply@yourdomain.com
Email address shown in the From field of outgoing messages. Required.

​
Realtime (PartySocket)

​
REALTIME_API_KEY

REALTIME_API_KEY=your-api-key
Shared secret used by the Builder and Worker to authenticate requests to the PartySocket service. Generate with: 
openssl rand -hex 32
Required. Must be the same value across all services.

​
Worker

​
SCHEDULER_BUCKET_RANGE

SCHEDULER_BUCKET_RANGE=0-255
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.