Configuration Reference
Complete documentation of environment variables for MultiWA Gateway.
Quick Reference
| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL | ✅ | - | PostgreSQL connection string |
REDIS_URL | ✅ | - | Redis connection string |
JWT_SECRET | ✅ | - | Secret key for JWT access tokens |
JWT_REFRESH_SECRET | ✅ | - | Secret key for JWT refresh tokens |
ALLOW_REGISTRATION | ❌ | false | Anyone may register (create an organization) after the first owner |
SESSIONS_DIR | ❌ | /data/sessions (Docker) | WhatsApp session storage path (env name in compose is SESSIONS_DIR) |
API_PORT | ❌ | 3000 (code) / 3333 (Docker compose) | API server port |
API_HOST | ❌ | 0.0.0.0 | API bind address |
NODE_ENV | ❌ | development | Environment mode |
CORS_ORIGINS | ❌ | http://localhost:3001,http://localhost:3333 (Docker) | Comma-separated allowed origins |
TRUST_PROXY | ❌ | - (172.16.0.0/12 in docker-compose.production.yml) | Address of the reverse proxy in front of the API, so rate limits and logins see the client's address |
NEXT_PUBLIC_API_URL | ❌ | http://localhost:3333 (Docker) | URL the browser uses to reach the API. Build-time in the admin image. |
DEFAULT_ENGINE | ❌ | whatsapp-web-js | WhatsApp engine (whatsapp-web-js or baileys) |
ENGINE_HOST | ❌ | api | Where the engine runs: api or worker |
DURABLE_SEND | ❌ | false | Enqueue outbound sends in Redis (BullMQ) with retry |
OUTBOUND_SEND_CONCURRENCY | ❌ | 10 | Max concurrent durable send deliveries |
SEND_TIMEOUT_MS | ❌ | 60000 | The longest one WhatsApp send may take before it fails with 504 SEND_TIMEOUT |
WWEBJS_MEMORY_LIMIT_MB | ❌ | 2500 | Memory (MB) above which a profile's Chromium is restarted from its session; 0 = off |
WEBHOOK_TIMEOUT_MS | ❌ | 30000 | Webhook delivery timeout |
WEBHOOK_ALLOW_PRIVATE_TARGETS | ❌ | false | Allow webhook, AI and customer lookup targets on private networks (SSRF guard) |
QUIET_ALARM_ACTIVE_HOURS | ❌ | 07:00-22:00 | Daily window in which a connected profile's silence counts toward its quiet-profile alarm |
QUIET_ALARM_TIMEZONE | ❌ | Asia/Jakarta | Time zone of that window |
CALL_RING_TIMEOUT_MS | ❌ | 90000 | A call still ringing after this long is closed as unknown |
CALL_LOG_GRACE_MS | ❌ | 60000 | How long a call that stopped ringing as unknown waits for WhatsApp's call log before the team is told about an unanswered call |
CALLS_MEDIA_ENABLED | ❌ | false | Answering calls in the dashboard: the media server's switch |
CALLS_MEDIA_ANNOUNCED_ADDRESS | with CALLS_MEDIA_ENABLED | - | The address agents' browsers reach the media port on |
CALLS_MAX_TALK_MINUTES | ❌ | 120 | A call answered in the dashboard is hung up after this long |
CALLS_MAX_VIDEO_CALLS | ❌ | 2 | How many calls the server answers with video at once; past it, and with 0, video calls are answered as voice |
CALL_RECORDINGS_STORAGE | ❌ | STORAGE_TYPE, else local | Where call recordings go: local or s3 |
CALL_RECORDINGS_PATH | for local recordings | - (Docker: /data/call-recordings) | The directory of local call recordings |
CALL_RECORDINGS_TMP | for recording | - (Docker: /data/call-recordings-tmp) | The directory of recordings in progress |
Database
DATABASE_URL
Required | String
PostgreSQL connection string in the following format:
postgresql://[user]:[password]@[host]:[port]/[database]?sslmode=[mode]
Example:
# Development
DATABASE_URL=postgresql://multiwa:multiwa_password@localhost:5432/multiwa_gateway
# Production (with SSL)
DATABASE_URL=postgresql://user:password@db.host.com:5432/multiwa?sslmode=require
Redis
REDIS_URL
Required | String
Redis connection string for queue and caching.
# Development
REDIS_URL=redis://localhost:6379
# Production (with password)
REDIS_URL=redis://:password@redis.host.com:6379
Authentication
JWT_SECRET
Required | String (min 32 characters)
Secret key for signing JWT tokens. MUST be changed in production!
# Generate secure secret
openssl rand -base64 32
JWT_EXPIRES_IN
Optional | String | Default: 7d
JWT token validity duration. Format: Xd (days), Xh (hours), Xm (minutes).
JWT_EXPIRES_IN=7d # 7 days
JWT_EXPIRES_IN=24h # 24 hours
ENCRYPTION_KEY
Optional | String (32 characters)
Key for encrypting sensitive data (API keys, credentials).
# Generate 32-character key
openssl rand -hex 16
ALLOW_REGISTRATION
Whether anyone may create an account, and with it a new organization. The first person on a new server always may: they become its owner, and the owner of the server's settings (SMTP, storage, integrations). Until that first account exists, anyone who reaches the server can claim it, so create it before you expose the server. After that, registration is closed unless ALLOW_REGISTRATION=true, and owners and admins add people in Settings → Team. The value must be exactly true: any other value (TRUE, 1, yes) keeps registration closed. Set it to true only for a server that hosts many organizations on purpose.
API Server
API_PORT
Optional | Number | Default: 3000 (when running locally with pnpm --filter api dev) or 3333 (Docker compose default)
Port for the NestJS API server. The Docker Compose file overrides this to 3333 so the in-container port and the host port mapping line up ("${API_PORT:-3333}:3333"). Public docs and examples use 3333 because that is the Docker default.
API_HOST
Optional | String | Default: 0.0.0.0
Host binding for the API server.
CORS_ORIGINS
Optional | String (comma-separated)
Allowed origins for CORS. Separate multiple origins with commas.
# Development
CORS_ORIGINS=http://localhost:3000,http://localhost:3001
# Production
CORS_ORIGINS=https://admin.yourdomain.com,https://app.yourdomain.com
TRUST_PROXY
Optional | String (comma-separated IP addresses or CIDRs) | Default: unset (172.16.0.0/12 in docker-compose.production.yml)
The address of the reverse proxy in front of the API. Without it, behind nginx every request comes from nginx's address: every client shares one rate limit, and logins record nginx's address. With it, the API takes the client address that proxy appended to X-Forwarded-For.
Only the hop that connects to the API is trusted, and only from a listed address, so a client cannot choose its address by sending its own X-Forwarded-For. Keep client networks out of the list: a client that connects to the API port directly from a listed address is taken for the proxy. A value that is not an address list, such as 1 or true, stops the API at boot.
# nginx on a Docker network of the stock compose files
TRUST_PROXY=172.16.0.0/12
WhatsApp Sessions
SESSIONS_DIR
Optional | String | Default: /data/sessions (Docker)
Directory for storing WhatsApp session data (whatsapp-web.js auth files and Baileys keystore). The Docker compose file maps this to the sessions_data named volume.
# Local development
SESSIONS_DIR=./sessions
# Docker (matches compose default)
SESSIONS_DIR=/data/sessions
⚠️ Important: This path must be persistent (a named Docker volume or a host bind mount) so sessions are not lost when the container restarts. Treat session files like a credential: anyone with the files can impersonate the connected WhatsApp number.
Rate Limiting
The API allows 120 requests per minute per route and client address (the global
ThrottlerGuard; some routes, such as POST /auth/register, allow fewer). The limit
is not set by an environment variable. Behind a reverse proxy, set
TRUST_PROXY so the client address is the caller's, not the proxy's.
Worker
WORKER_CONCURRENCY
Optional | Number | Default: 10
Number of concurrent jobs processed by the worker.
# Low-resource server
WORKER_CONCURRENCY=5
# High-performance server
WORKER_CONCURRENCY=20
Engine Hosting
Where the WhatsApp engine runs — api (default) or worker.
ENGINE_HOST
Optional | api | worker | Default: api
Selects the process that owns the WhatsApp engine sessions:
api(default) — the engine lives in the API process (current behaviour).worker— the engine runs inapps/worker; the API delegates engine operations over BullMQ. The worker must be running and share the API's sessions volume.
The API and the worker must see the same value. The stock Compose files with a
worker give both services the one in .env.
ENGINE_HOST=api
WhatsApp Web Engine
A profile on the whatsapp-web-js engine runs its own headless Chromium. When that page crashes or the
browser dies (for example when the host runs out of memory and the kernel kills it), the profile's engine is
restarted from its stored session automatically, without a QR, and the other profiles are not touched.
WWEBJS_MEMORY_LIMIT_MB
Optional | Number (MB) | Default: 2500
The memory a profile's Chromium (the browser and its pages) may hold before that profile's engine is restarted
from its session, checked every minute while the profile is online. A WhatsApp Web page grows over days; on a
small host one page can take enough memory for the kernel to kill processes. 0 turns the check off. It is
measured on Linux only. The restart briefly takes that profile offline (up to a few minutes). A profile on a
call (its audio in the dashboard, or being recorded) is restarted only once the call ends, if it is still over
the limit then. A profile restarted for memory is not restarted for memory again within 30 minutes, so a limit
below its normal size cannot keep it offline; raise the limit if the log says so. A crash is still recovered in
that time.
WWEBJS_MEMORY_LIMIT_MB=2500
Send Timeout
SEND_TIMEOUT_MS
Optional | Number (ms) | Default: 60000
The longest one WhatsApp send may take. A profile's sends go out one after another,
so a send that hangs would hold every later send of that profile.
Past this bound the send fails with 504 SEND_TIMEOUT and the next one goes. The
message is stored as failed, but WhatsApp may still deliver it, so the gateway
never retries a timed-out send. A normal send takes seconds; raise this for large
media over a slow link.
SEND_TIMEOUT_MS=60000
Durable Sending
Outbound sends are synchronous by default. When DURABLE_SEND=true they are
enqueued in Redis (BullMQ) and delivered by an in-process consumer with retry —
the API returns 202 { status: "queued" } immediately and delivery is reported
via message.status and message.sent/message.failed webhooks.
DURABLE_SEND
Optional | Boolean | Default: false
DURABLE_SEND=true
OUTBOUND_SEND_CONCURRENCY
Optional | Number | Default: 10
Maximum concurrent deliveries from the durable send queue.
OUTBOUND_SEND_CONCURRENCY=10
Webhook
Delivery knobs: the retry policy (attempts/backoff) and per-attempt timeout are read from these env vars by the worker's webhook dispatcher/processor.
WEBHOOK_TIMEOUT_MS
Optional | Number | Default: 30000
Timeout in milliseconds for webhook delivery.
WEBHOOK_RETRY_ATTEMPTS
Optional | Number | Default: 5
Number of delivery attempts (BullMQ job attempts) if a webhook delivery fails. Defaults to the historical fixed policy of 5 attempts.
WEBHOOK_RETRY_DELAY_MS
Optional | Number | Default: 30000
Base delay (ms) between retries (exponential backoff). Defaults to the historical fixed policy of 30s.
WEBHOOK_ALLOW_PRIVATE_TARGETS
Optional | Boolean | Default: false
SSRF guard for tenant-controlled URLs (webhook targets, custom-AI endpoints,
the customer lookup URL). By default targets that resolve to loopback, private,
link-local or reserved addresses are blocked (cloud metadata
169.254.169.254 is always blocked, even when this is true). Self-hosted
deployments that deliver to internal services on the same network (Chatwoot,
Typebot, n8n, localhost) set this to true to allow private targets. With it
set, a localhost or 127.0.0.1 host is first rewritten to
host.docker.internal, which must resolve from MultiWA's containers: under
Docker, name the target by its service name or LAN address instead. Leave
false for public / multi-tenant deployments.
# Allow webhooks to reach internal services on the same network
WEBHOOK_ALLOW_PRIVATE_TARGETS=true
Quiet-Profile Alarm
A profile can stay connected while WhatsApp has stopped delivering messages to
it, and nothing reports a disconnect. The quiet-profile alarm catches this: when
a connected profile receives no incoming message for a set number of hours, it
raises one alarm (an admin bell notification, plus a WhatsApp message to your
ops numbers through another connected profile of the same organization) and
one notice when messages resume. Profiles are checked every 5 minutes. A
disconnected profile never raises the alarm: the disconnect alert covers that.
The alarm is set per profile, on the profile page or with
PUT /api/v1/profiles/:id:
quietAlarmHours— whole hours, 1 to 72, of silence before the alarm.null(or blank on the profile page) turns it off, which is the default.quietAlarmNotify— up to 5 WhatsApp numbers that get the message. The profile's own number is skipped, and@broadcastand@newsletteraddresses are refused.
Set it on profiles that normally receive messages throughout the active hours: a profile that is quiet for long stretches will raise and recover regularly.
Silence is counted only inside a daily active window, so a quiet night does not
raise an alarm. Two variables set that window. The stock compose files do not
forward them: add them under environment: of the API service to override the
defaults.
QUIET_ALARM_ACTIVE_HOURS
Optional | HH:MM-HH:MM | Default: 07:00-22:00
Daily window in which a connected profile's silence counts, in the time zone below. The start is included, the end is not, the window cannot cross midnight and it must last at least an hour. An invalid value falls back to the default.
QUIET_ALARM_TIMEZONE
Optional | IANA time zone | Default: Asia/Jakarta
Time zone of that window, also used for the times written in the alarm message. An unknown zone falls back to the default.
# Count silence from 08:00 to 20:00 Jakarta time
QUIET_ALARM_ACTIVE_HOURS=08:00-20:00
QUIET_ALARM_TIMEZONE=Asia/Jakarta
Calls
Timers for incoming WhatsApp calls. They are read by the process that hosts the engine: the API by default, the worker with ENGINE_HOST=worker. The stock Compose files do not pass them through, so add them to the environment: of that service. A value that is not a positive number falls back to the default.
CALL_RING_TIMEOUT_MS
Optional | Number (milliseconds) | Default: 90000
How long a call may stay ringing before MultiWA gives up on it and closes it as unknown, and tells your team about an unanswered call. It is the safety net for a call whose end the engine never reported. WhatsApp's call log can still settle the call afterwards (a call.updated webhook).
CALL_LOG_GRACE_MS
Optional | Number (milliseconds) | Default: 60000
A call that stopped ringing as unknown usually gets its real outcome (missed, rejected, answered on another device) from WhatsApp's call-log message within moments. If none has arrived after this long, MultiWA tells your team about an unanswered call. The call stays unknown until a call log settles it.
CALL_RING_TIMEOUT_MS=90000
CALL_LOG_GRACE_MS=60000
The timers live in memory. When the engine host starts, every call still ringing is closed as unknown at once, whatever its age, and no call.ended webhook is sent for it. It stays unknown, since an engine passes on only the call log of a call it saw ringing since it last connected.
Calls answered in the dashboard
Agents can answer a profile's incoming calls in the dashboard (PUT /profiles/:id/calls-settings) through a media server in the API. It runs only where the API hosts the engines (ENGINE_HOST=api). The stock Compose files pass these settings to the API, except the last two (add those to the environment: of the API service); publish the media port by adding docker-compose.calls-media.yml.
CALLS_MEDIA_ENABLED
Optional | true / false | Default: false
The server switch. Off, the media server never starts and no profile can turn dashboard answering on. Changing it needs an API restart.
CALLS_MEDIA_PORT
Optional | Port | Default: 40000
The one UDP+TCP port of all call audio. Agents' PCs must reach it (UDP preferred, TCP as the fallback).
CALLS_MEDIA_ANNOUNCED_ADDRESS
Required when CALLS_MEDIA_ENABLED=true | IP address or host name
The address agents' browsers reach the media port on, e.g. the server's LAN address. The API does not start without it.
CALLS_MEDIA_LISTEN_IP
Optional | IPv4 address | Default: the first external interface
The local address the media server listens on. Set it when the host has several interfaces or the API uses host networking.
CALLS_MEDIA_ICE_SERVERS
Optional | JSON
ICE servers for agents' browsers, e.g. a TURN server for agents outside the LAN: [{"urls":"turn:turn.example.com:3478","username":"u","credential":"p"}].
CALLS_MAX_TALK_MINUTES
Optional | Number (minutes) | Default: 120
A call answered in the dashboard is hung up after this long (endReason: time_limit).
CALLS_CONNECT_TIMEOUT_MS
Optional | Number (milliseconds) | Default: 10000
From an agent's Answer to its audio connected. Past it the answer is undone and the call rings again for every agent, unless WhatsApp was already answering it: it is hung up then.
CALLS_AGENT_GRACE_MS
Optional | Number (milliseconds) | Default: 15000
An agent whose browser has no connection to the API, or whose audio link is down, for this long is hung up (endReason: agent_lost). A reloaded agent page rejoins its call within it. The WhatsApp Web page's own audio link down for as long ends the call too (endReason: media_failed). It is also how long an agent's "unavailable" outlives their last socket: a reload keeps it, and closing the dashboard ends it. The API keeps it in memory, so a restart of the API (a deploy too) forgets it: every agent who had turned calls off is available, and rung, again.
CALLS_MAX_VIDEO_CALLS
Optional | Number (0 or more) | Default: 2
How many calls the server answers with video at once, for every organization. A video call past it is answered as voice, and its banner says the server is busy. 0 answers every video call as voice. Each video call costs the WhatsApp Web page about 1 GB of memory and close to a CPU core (Chromium encodes VP8 without a GPU), so raise it only on a server with room for that.
CALLS_MEDIA_ENABLED=true
CALLS_MEDIA_ANNOUNCED_ADDRESS=192.0.2.10
CALLS_MAX_TALK_MINUTES=120
Call recordings
Calls answered in the dashboard can be recorded (PUT /profiles/:id/calls-settings with recording: true), always with an announcement the caller hears first (POST /profiles/:id/calls-announcement). Recordings and announcements are private:
- nothing serves them without the login of an owner or admin of their organization;
- every play and download is audited;
- recording cannot be turned on unless the storage refuses reads without credentials. The API checks this then, and again every night at 02:30 server time (
TZ). When a check finds the storage public (the nightly one, or the one run to turn recording on), recording is turned off on every profile, and every organization with recording on or recordings stored is alerted: its owners and admins get a bell notification, and the quiet-profile alarm numbers of its profiles (quietAlarmNotify) a WhatsApp message. A nightly check that proves nothing alerts the organizations whose profiles record the same way, and leaves recording on.
A recorded call is recorded in stereo, from before the announcement: left the caller, right what the caller heard (the announcement, then the agent). The agent is connected once the announcement has played. When the recorder does not start, or the announcement does not play, the call goes on unrecorded with the agent connected, and the owners and admins are told the same way (each at most once an hour per profile).
When recording is on for a profile but this server's recordings storage, or CALL_RECORDINGS_TMP, is not set up, its calls are not recorded, and every night its organization's owners and admins are reminded.
A recording is written to CALL_RECORDINGS_TMP while its call lasts, and stored when the call ends, with four tries over about 40 seconds. When they all fail, it stays on the server, the owners and admins are told, and it is tried again at the next start and every night. It is never stored to a storage last found public, and it is deleted unstored once older than its profile's retention period. A recording cut short by a restart is stored at the next start, marked partial.
The same nightly job deletes the recordings older than each profile's retention period (retentionDays, 90 by default). It also deletes the files nothing points at any more (for one, those of a deleted workspace or organization; a deleted profile's files are deleted with it). The stock Compose files pass all six settings below to the API.
⚠️ One recordings location per MultiWA database: never point two installations, or a restored copy, at the same bucket and prefix or the same directory — each night each would delete the other's files.
CALL_RECORDINGS_STORAGE
Optional | local / s3 | Default: STORAGE_TYPE, else local
Where recordings go. Media can stay local while recordings go to a bucket, or the other way round. Changing it leaves the recordings already stored behind: this server can neither play nor delete them until it uses that storage again (retention skips them, and the log says how many).
CALL_RECORDINGS_PATH
Required for local recordings | Path | Docker Compose: /data/call-recordings (volume call_recordings)
A directory of their own, on a persistent volume.
- It must not be inside or around
STORAGE_PATH(served without a login) orSESSIONS_DIR(its backups would carry every recording), nor around the API's working directory (the nightly sweep would walk the whole application). - It must belong to the API's user alone. It is made 0700; one of another user, a shared (sticky) directory such as
/tmp, or a symlink is refused. The API image runs as root, so a named Docker volume is made 0700; a bind mount must belong to the container's user. - Unset or refused, recording cannot be turned on.
GET /calls/media/statussays why, inserver.recordings.problem.
CALL_RECORDINGS_BUCKET
Optional | Bucket name | Default: S3_BUCKET
- S3 recordings need
S3_ENDPOINT,S3_ACCESS_KEYandS3_SECRET_KEY, and useS3_REGION(defaultus-east-1). - A private bucket of their own is strongly advised. Objects are written without an ACL, so they are as private as the bucket.
- The check fetches a probe without credentials at
S3_ENDPOINT, and atS3_PUBLIC_URLwhen it is set (a loopbackS3_PUBLIC_URL, such as the dev compose'shttp://localhost:9000, is the same server and is not fetched twice). A refusal (400,401,403or404) or a page that is not the probe (a login page) passes, the probe's own bytes arestorage_not_private, and any other answer, or none within 5 seconds, isstorage_check_failed. - The check sees only those addresses. Turn off every other public way to the recordings bucket: a public bucket URL (Cloudflare R2's
r2.dev, a custom domain) or a CDN that reads the bucket on its own credentials. - Keep versioning off on the recordings bucket, or expire noncurrent versions with a lifecycle rule: with versioning on, a deleted recording stays as a noncurrent version.
- Compatible stores: AWS S3, MinIO, Wasabi, Backblaze B2, Cloudflare R2, DigitalOcean Spaces, and Google Cloud Storage (XML API).
CALL_RECORDINGS_PREFIX
Optional | Key prefix | Default: call-recordings/
Letters, digits, ., _, - and / only, without a . or .. segment; another value leaves recording unavailable (server.recordings.problem says why).
Changing it, the bucket or CALL_RECORDINGS_PATH leaves the recordings already stored behind: each recording remembers its location (s3:<bucket>/<prefix> or local:<path>), and this server neither plays nor deletes one stored elsewhere (retention skips them, and the log says how many). To move them, copy the objects to the new location first, then point their rows at it: UPDATE call_recordings SET "storageLocation" = '<new>' WHERE "storageLocation" = '<old>';. Another provider with the same bucket and prefix keeps the same location (the endpoint is not part of it): copy the objects before switching, or deletes and retention would mark rows deleted while their files stay at the old provider.
CALL_RECORDINGS_SSE
Optional | AES256 / aws:kms
Server-side encryption of every object, for stores that support it. Another value leaves recording unavailable.
CALL_RECORDINGS_STORAGE=s3
CALL_RECORDINGS_BUCKET=multiwa-call-recordings
CALL_RECORDINGS_SSE=AES256
CALL_RECORDINGS_TMP
Required for recording | Path | Docker Compose: /data/call-recordings-tmp (volume call_recordings_tmp)
Where a recording is written while its call lasts, whatever CALL_RECORDINGS_STORAGE is. It holds about 0.5 MB a minute per recorded call, and as much again for a moment while that call's recording is stored.
- On a persistent volume, a recording cut short by a restart is stored at the next start (
partial). Elsewhere, it is lost with the container. - The same rules as
CALL_RECORDINGS_PATHapply: not inside or aroundSTORAGE_PATH,SESSIONS_DIRorCALL_RECORDINGS_PATH, nor around the API's working directory. - It must belong to the API's user alone. It is made 0700; one of another user, a shared (sticky) directory such as
/tmp, or a symlink is refused. The API image runs as root, so a named Docker volume is made 0700; a bind mount must belong to the container's user. - Unset or refused, recording cannot be turned on, and
GET /calls/media/statussays why, inserver.recordings.problem. Recordings already stored stay playable, deletable and under retention. - One per API process: two processes sharing one would take each other's recordings in progress for leftovers. (The engines run in one API process; that is the supported setup.)
Logging
LOG_LEVEL
Optional | String | Default: info
Logging level: debug, info, warn, error.
# Development (verbose)
LOG_LEVEL=debug
# Production (minimal)
LOG_LEVEL=warn
NODE_ENV
Optional | String | Default: development
Environment mode: development, production, test.
Admin UI (Next.js)
NEXT_PUBLIC_API_URL
Required for Admin | String
API backend URL for the Admin UI. This value is baked into the Next.js client bundle at build time. Changing it in .env alone is not enough — you must rebuild the admin image, for example:
docker compose build --no-cache admin
docker compose up -d --no-deps --force-recreate admin
# Docker default (matches docker-compose.yml)
NEXT_PUBLIC_API_URL=http://localhost:3333
# Production behind a reverse proxy on the same origin
NEXT_PUBLIC_API_URL=https://multiwa.example.com
# Production with a dedicated API subdomain
NEXT_PUBLIC_API_URL=https://api.example.com
Optional Services
Sentry (Error Tracking)
Optional. With SENTRY_DSN set, the API and the worker send their errors to that Sentry project (sentry.io or
self-hosted): an error behind a 500 that Nest did not expect, a crash of the process, and a queue job's last failed
attempt (an attempt BullMQ retries is not sent). Errors only: no tracing, no profiling. Unset, nothing is sent.
SENTRY_DSN=https://<public-key>@sentry.example.com/<project-id>
# Optional, default NODE_ENV
SENTRY_ENVIRONMENT=production
Each event carries the tag service (api or worker) and the release multiwa@<version>. Nothing personal is sent:
a request keeps its method and path (no query string, headers, cookies or body), no user is set, phone numbers, chat
ids and emails are replaced in every message, a Prisma error keeps its first line and its reason (not the query
between them), and log lines are not sent as breadcrumbs. Both containers must reach the DSN's host over HTTPS.
MinIO (S3-compatible Storage)
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=multiwa-media
MINIO_USE_SSL=false
Example Configurations
Development (.env)
DATABASE_URL=postgresql://multiwa:multiwa_password@localhost:5432/multiwa_gateway
REDIS_URL=redis://localhost:6379
JWT_SECRET=development-secret-key-change-in-production
JWT_EXPIRES_IN=7d
API_PORT=3000
CORS_ORIGINS=http://localhost:3000,http://localhost:3001
SESSIONS_PATH=./sessions
LOG_LEVEL=debug
NODE_ENV=development
Production (.env.production)
DATABASE_URL=postgresql://user:password@db.host.com:5432/multiwa?sslmode=require
REDIS_URL=redis://:password@redis.host.com:6379
JWT_SECRET=your-secure-generated-secret-key-here
JWT_REFRESH_SECRET=another-independent-secret-here
ENCRYPTION_KEY=32-hex-chars-from-openssl-rand-hex-32
JWT_EXPIRES_IN=7d
API_PORT=3333
CORS_ORIGINS=https://admin.yourdomain.com
NEXT_PUBLIC_API_URL=https://multiwa.yourdomain.com
SESSIONS_DIR=/data/sessions
LOG_LEVEL=warn
NODE_ENV=production
RATE_LIMIT_MAX=100
RATE_LIMIT_TTL=60
Security Checklist
-
JWT_SECRETandJWT_REFRESH_SECRETare independent random strings of 32+ characters (generated withopenssl rand -base64 64). -
ENCRYPTION_KEYis set (openssl rand -hex 32) so credential fields are encrypted at rest. -
DATABASE_URLuses SSL in production. -
CORS_ORIGINSonly whitelists required domains (nolocalhostin production). -
LOG_LEVELset towarnorerrorin production. -
SESSIONS_DIRuses a persistent volume and is backed up like credentials. -
NEXT_PUBLIC_API_URLmatches the public URL the browser will hit, and the admin image was rebuilt after setting it. -
NODE_ENV=productionis set.