Configuration and Environment Variables

Configuration & Environment Variables

ForgeChat is configured through a single file, backend/.env. Copy the template and fill it in:

cp backend/.env.example backend/.env

Never commit backend/.env or any real secret to git. Generate secrets with openssl rand -hex 32. In production the backend refuses to start if JWT_SECRET or FORGECRM_ENCRYPTION_KEY is missing, left at its placeholder, or shorter than 32 characters.

App

Variable	Purpose	Required	Example
PORT	Port the backend listens on	Yes	3011 (Docker) / 3001 (local dev)
NODE_ENV	Run mode	Yes	production

PostgreSQL

Variable	Purpose	Required	Example
DATABASE_URL	Primary connection string	Yes	postgresql://postgres:<pass>@forgecrm-db:5432/postgres
POSTGRES_PASSWORD	Password used to initialise the bundled DB container — must match the password in DATABASE_URL	Yes	a strong random string
POSTGRES_SSL	Enable TLS to the database	No	false
DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD	Discrete fallback params, used only if DATABASE_URL is unset	No	—

Redis

Variable	Purpose	Required	Example
REDIS_URL	Redis connection for the message-send & media-download queues	Yes	redis://redis:6379

Authentication & encryption

Variable	Purpose	Required	Example
JWT_SECRET	Signs login (JWT) tokens; minimum 32 characters in production	Yes	openssl rand -hex 32
FORGECRM_ENCRYPTION_KEY	Passphrase for encrypting stored Meta access tokens (AES-256-GCM)	Yes (prod)	a different openssl rand -hex 32

First-run admin

These seed the first admin user, and are only used when the users table is empty.

Variable	Purpose	Required	Example
ADMIN_EMAIL	Email for the first admin user	Yes	admin@forgechat.local
ADMIN_PASSWORD	Password for that admin user	Yes (prod)	a strong password

CORS

Variable	Purpose	Required	Example
CORS_ORIGIN	The URL the browser loads the dashboard from	Yes	http://localhost or https://chat.yourbusiness.com

Meta WhatsApp Cloud API

These are only needed for live WhatsApp send/receive — leave them unset to explore the UI without making real Meta calls.

Variable	Purpose	Required	Example
META_API_VERSION	Graph API version	No	v21.0
META_WEBHOOK_VERIFY_TOKEN	Token Meta echoes back when verifying your webhook	For live use	a random string you choose
META_ACCESS_TOKEN	Legacy single-account token (per-account tokens entered in the dashboard are preferred)	No	—

Optional tuning

All optional; defaults shown. Uncomment in backend/.env.example to override.

Variable	Default	Purpose
MEDIA_DIR	./media	Where downloaded chat media is stored
MEDIA_TRANSCODE_AUDIO	true	ffmpeg audio fallback for Safari
MEDIA_QUEUE_CONCURRENCY / MEDIA_QUEUE_ATTEMPTS / MEDIA_QUEUE_BACKOFF_MS	2 / 3 / 5000	Media-download queue behaviour
SEND_QUEUE_CONCURRENCY / SEND_QUEUE_ATTEMPTS	10 / 3	Outbound send queue behaviour
SEND_RATE_MAX / SEND_RATE_DURATION_MS	60 / 1000	Outbound rate limit (messages per window)
TEMPLATE_SYNC_INTERVAL_MS	14400000	How often template approval status is synced from Meta

---

See also: Installation • WhatsApp Business API / Meta Setup • Security