Environment Variables & Security

Comprehensive reference of required and optional configuration keys for production JChat.

The Production .env Template

Copy .env.example to .env (cp .env.example .env) or configure these variables in your deployment environment:

# Server & Network
JCHAT_PORT="3000"
JCHAT_DOMAIN="chat.example.com"
JCHAT_SITE_URL="https://chat.example.com"
JCHAT_ROUTING_MODE="path"
NODE_ENV="production"
RUNTIME="bun"

# Security & Session Secrets
JCHAT_COOKIE_SECRET="generate-64-character-hex-string"
JCHAT_ADDON_ENCRYPTION_KEY="generate-64-character-hex-string"

# Relational Database & Redis Cache
JCHAT_DATABASE_URL="postgresql://jchat:password@localhost:5432/jchat"
JCHAT_REDIS_DATABASE_URL="redis://default:password@localhost:6379"

Environment Variables Reference

Detailed breakdown of each configuration section:

1. Server & Domain Configuration

JCHAT_PORT: Internal port the Bun/Elysia HTTP and WebSocket engine listens on (default: 3000).

JCHAT_DOMAIN: Primary canonical domain (e.g. example.com).

JCHAT_SITE_URL: Full canonical public URL with protocol (e.g. https://example.com). Crucial for CORS, OAuth callbacks, and WebSocket origin validation.

JCHAT_ROUTING_MODE: Multi-site routing architecture:

path (Default): All sites and panels live on the primary domain (example.com/:siteSlug and example.com/manage).
subdomain: Sites receive dedicated subdomains (:siteSlug.example.com). In this mode, the Unified Management Portal lives exclusively on the dedicated manage subdomain (manage.example.com/manage).

NODE_ENV: Set to production. RUNTIME: Keep as bun.

JCHAT_COOKIE_SECRET: High-entropy 64-character hex string used to sign and encrypt HTTP session cookies. JCHAT_ADDON_ENCRYPTION_KEY: 64-character hex key used to encrypt sensitive addon configuration settings and API keys.

3. Database & Redis Persistence

JCHAT_DATABASE_URL: Full PostgreSQL 18 connection string (postgresql://user:pass@host:5432/dbname). JCHAT_REDIS_DATABASE_URL: Redis 7+ connection URL (redis://[:pass@]host:6379) used for real-time WebSocket pub/sub message distribution across workers.

4. Media Storage Backends

Media storage backends (Local Disk, Cloudflare R2, Amazon S3, MinIO, Google Cloud Storage) are configured and encrypted directly in the database via the Unified Management Portal (Manage > Settings > Storage). Changes take effect dynamically across all cluster nodes with zero server restarts.