Deploy OpenWA to production with Docker
This guide takes you from a fresh server to a hardened OpenWA deployment: the Compose stack and its profiles, the environment you must set, persistent storage, a TLS reverse proxy, health checks, and how to size the host. By the end you have a running API behind HTTPS that survives restarts and orchestrator probes.
OpenWA ships as one self-contained image. The NestJS REST API, the management dashboard,
and the real-time Socket.IO channel all share one port (2785) — there is no separate
dashboard container to deploy. OpenWA targets release v0.31.0.
- A Linux host with Docker Engine and the Docker Compose plugin.
- A domain name and TLS certificate (or a proxy that issues one, e.g. Caddy or Traefik with Let's Encrypt).
- A first-pass read of Configuration for the full environment-variable list.
OpenWA keeps live WhatsApp engine state in an in-memory map. Run one API container per session-data volume. Two replicas writing the same WhatsApp auth directory corrupt the session and force a logout. See Horizontal scaling for why and what a scale-out design would require.
How the pieces fit
The image bundles everything the API needs to boot with zero external dependencies. The optional datastores attach only when you turn on a Compose profile.
The default path — SQLite, local-disk storage, no cache — needs no companion containers. PostgreSQL, Redis, and MinIO are opt-in.
Start the Compose stack
The repository ships a hardened docker-compose.yml. The default profile runs the API with
SQLite and local file storage, so a minimal deployment needs no external database. Check out a
release tag, as below, rather than building the default branch: it holds whatever has merged since
the last release, migrations included. Upgrade later with git fetch --tags && git checkout v<new-version>
instead of git pull (see the Migration guide).
# <release> is the release to deploy, see https://github.com/rmyndharis/OpenWA/releases
git clone --branch v<release> https://github.com/rmyndharis/OpenWA.git && cd OpenWA && cp .env.example .env
# Edit .env — at minimum set a strong API_MASTER_KEY (see "Required environment").
docker compose up -d
The container publishes port 2785 to 127.0.0.1 only, so it is reachable from the host
but not directly from the network. Before Docker Engine 28.0.0, hosts on the same network
segment can still reach a port published to localhost (see
Bind address and TLS). Confirm it came up
healthy before exposing it:
curl http://localhost:2785/api/health -H "X-API-Key: YOUR_API_KEY"
{ "status": "ok", "timestamp": "2026-06-26T10:00:00.000Z", "version": "0.31.0" }
A keyless probe gets the same 200 without the version field — since v0.19.0 it is disclosed only to callers presenting a valid API key.
Opt into PostgreSQL, Redis, or MinIO
The built-in datastores live behind Compose profiles. Enable them by name and set the matching environment variables so the API connects to the new service.
# API + built-in PostgreSQL
docker compose --profile postgres up -d
# API + PostgreSQL + Redis + MinIO
docker compose --profile full up -d
| Profile | Adds | Requires |
|---|---|---|
postgres | PostgreSQL 16 | DATABASE_TYPE=postgres, DATABASE_HOST=postgres, DATABASE_PORT=5432, DATABASE_USERNAME=openwa, a non-empty DATABASE_PASSWORD |
redis | Redis 7 | REDIS_ENABLED=true, REDIS_HOST=redis |
minio | MinIO (S3-compatible) | STORAGE_TYPE=s3, S3_ENDPOINT=http://minio:9000, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY |
full | All of the above | The union of the rows above |
The host and port entries are load-bearing when you start a profile by hand: the compose file
forwards them but no longer defaults them, so a stack brought up with only DATABASE_TYPE or
REDIS_ENABLED set leaves the API pointed at localhost and unable to reach the container it
just started. The same applies to S3_ENDPOINT: leave it unset and the client addresses AWS S3
rather than the bundled MinIO. Saving the settings from the dashboard writes all of them for you.
The datastore containers refuse to start with an empty password, and OpenWA's production boot guard rejects empty or placeholder secrets — so a misconfiguration fails fast at boot instead of starting insecurely.
Required environment
Copy .env.example to .env and review it. The variables below matter most for a
production deployment. For the complete list, see the Configuration reference.
| Variable | Purpose | Production guidance |
|---|---|---|
NODE_ENV | Runtime mode | Set to production. Since v0.19.0 the runtime image sets this itself, and boot warns whenever it is unset or blank, whatever the listener is bound to. Unset silently degrades four controls to their dev posture: the default-secret assert is skipped, a wildcard CORS origin is allowed, Swagger UI is served, and validation error detail is exposed. |
API_MASTER_KEY | Master API key | Set this. Generate with openssl rand -base64 32. In production, boot is refused for a placeholder value and, since v0.19.0, for a key shorter than 32 characters. Leaving it unset or empty is allowed and is not a failure: first boot then generates a strong random key and writes it to /app/data/.api-key. Set it explicitly when you need the key to be stable across volumes. |
DATABASE_TYPE | Database backend | sqlite (default) or postgres. |
STORAGE_TYPE | Media storage backend | local (default) or s3. |
ENGINE_TYPE | WhatsApp engine | whatsapp-web.js (default, Chromium-based) or baileys (browser-free). Leave blank to let the dashboard's Infrastructure → Engine setting decide. |
SESSION_DATA_PATH | Where WhatsApp auth state is stored | Defaults to /app/data/sessions in the container. |
TZ | Process time zone | The image runs in UTC, and since v0.23.6 the bundled docker-compose.yml forwards TZ with a UTC default (up to v0.23.5 a TZ in .env never reached the container). Stored timestamps are UTC on both databases whatever it says (on PostgreSQL since v0.23.6; up to v0.23.5 the columns the gateway writes itself there took the process's zone); it sets the zone of every pretty log timestamp, framework lines such as [RoutesResolver] and [ExceptionsHandler] included (since v0.24.0 they go through the OpenWA logger like every other line). Under LOG_FORMAT=json, the production default, every entry keeps an ISO UTC timestamp. It also sets the local day the today message counts cover. |
CORS_ORIGINS | Allowed browser origins | The wildcard * is refused in production. Set explicit origins, e.g. https://dashboard.yourdomain.com. |
ENABLE_SWAGGER | Interactive API docs at /api/docs | See Swagger in production. |
API_MASTER_KEY, database passwords, and S3 credentials must come from your environment or a
secrets manager — never hardcode them in the image or in version control. For defense in
depth, set API_KEY_PEPPER before the first boot, so a database leak alone cannot precompute key
hashes. On a deployment that already has keys, setting or changing it makes every key, the admin
key included, answer 401, and none is left to re-issue the others. Restore the pepper the keys
were created under (unset it if they were created without one), or replace the admin key as in
Recover a lost admin key with the new pepper
exported, then re-issue the other keys.
On first boot, when no key exists yet, OpenWA seeds the admin key from API_MASTER_KEY, or
generates a random one if it is unset. When the key is generated, first boot prints it once in the startup banner (later
boots log only its first eight characters); since v0.28.0 a key supplied via API_MASTER_KEY is never printed to the startup banner (not even a prefix on later boots, and GET /api/auth/api-keys shows its prefix as (master key)). Either way, first boot writes the key to data/.api-key (mode 0600, or the path
in BOOTSTRAP_KEY_FILE), which scripts/backup.sh copies into every
archive while it exists. Nothing reads the file to authenticate, so you can delete it once the key
is stored elsewhere; if a log pipeline on an earlier release captured a supplied key, create a new admin key and revoke
that one. The file is kept honest: once its key no longer validates — checked by hash at boot, and
again on the revoke and delete paths — the file is removed, so it never advertises a dead
credential. The one exception is a pepper change: if a key row still carries the file's prefix but
the hash no longer matches (meaning API_KEY_PEPPER changed after the key was seeded), the file
survives and a boot WARN names the repair — restore the original pepper, or clear the api_keys
table and restart to seed a new admin key. A generated key survives restarts as long as
data/main.sqlite does; to get the same key on a new, empty data volume, set API_MASTER_KEY
before that volume's first boot. A value set later is not used to seed or replace the existing
admin key (production still checks it against the length and placeholder rules), so rotate by
creating a new ADMIN key and revoking the old one. See Authentication
for the full picture.
Persist data with volumes
All durable state lives under /app/data in the container, mounted to the named volume
openwa-data, which the bundled docker-compose.yml pins to the Docker name openwa_openwa-data
whatever the Compose project is called. This single volume holds:
- WhatsApp session auth — the linked-device credentials. Losing this forces a QR re-scan. The credential directories (engine profiles, Baileys auth state) are created owner-only (
0700) and re-tightened on every start since v0.20.0. - SQLite databases —
main.sqlite(API keys and audit log, always SQLite) andopenwa.sqlite(user data, whenDATABASE_TYPE=sqlite). - Local media — when
STORAGE_TYPE=local, underdata/media(STORAGE_LOCAL_PATH). Since v0.31.0 that directory is owner-only: the gateway sets it0700at every boot when it owns it, and writes new directories and files0700and0600. A process that reads it as another user, such as a static file server or a backup job under another uid, loses access: run it as the gateway's user (the image runs asopenwa). Files written earlier keep their mode but sit under the0700directory. A directory the gateway does not own keeps its mode, and the boot logs a warning while that mode lets other users in. WithSTORAGE_TYPE=s3the directory is set the same way and matters only while it holds files stored before the move to S3 or the fallback written while the bucket was unreachable. - Plugins, exports, and generated config. Since v0.31.0 the storage export archive is written
0600in a0700data/exports, and the next boot closes adata/exportsan earlier version left open, when the gateway owns it.
volumes:
- openwa-data:/app/data
If you enable PostgreSQL, Redis, or MinIO, each gets its own named volume (postgres-data,
redis-data, minio-data) so its data survives container recreation.
The session-auth directory and main.sqlite are the two pieces of state you cannot
regenerate — main.sqlite carries every API key and the audit log. Back up the whole volume
before upgrades, host moves, or anything that touches storage. The repo's scripts/backup.sh
captures both databases, sessions, local media, plugins, and bootstrap config in one archive; it
resolves database paths exactly like the app (MAIN_DATABASE_NAME / DATABASE_NAME, else the
fixed ./data defaults), takes an online-consistent snapshot via sqlite3 .backup in the
production image, and exits non-zero if a source database is missing or the archive comes out
incomplete. Since v0.22.0 the image also ships the PostgreSQL client, so backup.sh dumps a
DATABASE_TYPE=postgres data store in-container with pg_dump; earlier images carried neither
tool and a postgres backup exited 1. The restore is not symmetric: restore.sh puts back the
file-based state and stages the dump as database.sql in the data directory, then prints the
psql command you have to run yourself. Until you run it, the Postgres data store is untouched. Since v0.31.0 restore.sh also exits 1, before it writes anything, when the archive holds the SQLite data store (openwa.sqlite) and DATABASE_TYPE is postgres, because the app would never read that file. To run on SQLite again, change DATABASE_TYPE and DATABASE_NAME first, wherever they are set (an environment value, such as a Compose environment: entry or a Helm ConfigMap, outranks ./.env, which outranks the dashboard's .env.generated); to move a SQLite install to PostgreSQL, restore the archive into a SQLite install and move that install as the Migration guide describes.
Run inside the container, backup.sh needs BACKUP_DIR=/app/data/backups, and under Compose also
TMPDIR=/app/data/backups: the default ./backups sits on the read-only root filesystem, which
backup.sh refuses up front since v0.23.6, and the Compose /tmp is a tmpfs charged to the
container's memory limit. restore.sh takes no BACKUP_DIR; since v0.23.7 it needs
OPENWA_RESTORE_SNAPSHOT_DIR set to a writable directory outside the data directory, because its
safety snapshot copies the whole data directory and cannot be written into it. Under Compose set
TMPDIR on that mount too, so the extracted archive does not fill the memory-backed /tmp. Since v0.26.0 restore.sh also
stops before it copies anything, naming the key, when a path the archive's own .env.generated sets
(such as SESSION_DATA_PATH, PLUGINS_DIR or BOOTSTRAP_KEY_FILE) leads out of the data directory,
goes through a link that does not resolve, or lies inside or around another directory the restore
refills; set that key in the environment or ./.env to restore there. The default paths restore as
before, and since v0.28.0 restore.sh extracts with tar -P and unlinks any existing file or symlink at a target path before writing so a symlink inside the existing data directory cannot redirect extracted files outside it. See the
Migration guide for the commands.
Fix file ownership on bind mounts
The container starts as root, re-owns everything under /app/data to its openwa user (uid and
gid 997) on every start, and then drops to that user via gosu. A default start therefore needs
no chown on the host, and one to your own user would be undone at the next start. A container
started as another user (docker run --user, or user: in Compose) cannot re-own anything: the
bind-mounted directory must already be writable by that uid, and the entrypoint stops with
FATAL: ... is not writable otherwise. On a Docker daemon that runs as root, give the directory
to the image's user:
sudo chown -R 997:997 ./data
Put a reverse proxy and TLS in front
OpenWA does not terminate TLS itself. Put a reverse proxy (nginx, Caddy, Traefik, or a cloud
load balancer) in front of port 2785 and let it handle HTTPS. Because the REST API,
dashboard, and Socket.IO real-time channel all share one port, the proxy must forward
WebSocket upgrades and allow long-lived connections.
If you run behind a proxy and use per-key IP allowlists, also set TRUSTED_PROXIES to the
proxy's address or subnet so the real client IP is read from X-Forwarded-For. Left unset,
OpenWA ignores that header (preventing IP spoofing).
The production default also makes browsers upgrade the dashboard's own requests to HTTPS
(CSP_UPGRADE_INSECURE_REQUESTS), which is right behind this proxy. To serve the dashboard over
plain HTTP instead, for example host:port on a trusted private network, set
CSP_UPGRADE_INSECURE_REQUESTS=false (both Compose files forward it from .env; pass -e to
docker run). With the default left on, the gateway's boot warning says: "If this instance is
reached over plain HTTP, the browser will upgrade the UI's scripts to https:// and the dashboard
will render blank."
nginx
server {
listen 443 ssl;
server_name api.example.com;
# ssl_certificate / ssl_certificate_key ...
location / {
proxy_pass http://127.0.0.1:2785;
proxy_http_version 1.1;
# Base64 media rides in the JSON body, and nginx refuses bodies
# above 1m by default (413). Allow at least BODY_SIZE_LIMIT
# (25mb by default) and raise both together
client_max_body_size 30m;
# Required for the Socket.IO real-time channel
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Long-lived connections for real-time updates
proxy_read_timeout 600s;
proxy_send_timeout 600s;
}
}
Traefik
Traefik forwards WebSocket upgrades automatically, so a normal HTTP router works. Two things keep a public deployment stable:
- Route over the Docker network — don't also publish the host port. If OpenWA both
publishes
2785:2785to the host and is routed through Traefik, every request makes an extra hop through Docker'sdocker-proxy. Because OpenWA holds a long-lived Socket.IO connection per client, those held-open connections accumulate across both hops and can exhaust the upstream pool — the dashboard, API, and real-time channel then return504together whilecurl …/api/health/readyon the host still returns200. Put the service on the proxy's shared network andexposethe port internally instead of publishing it. - Use generous idle timeouts (for example 600s) so the proxy does not cut the persistent Socket.IO connection.
The example below uses the published image rmyndharis/openwa:latest as a drop-in
alternative to building from source. Since v0.11.0, :latest moves only when a tagged release
passes the release workflow's boot-smoke gate — a merge to main no longer re-points it. Since v0.26.0 latest and the X.Y channels also never move to an older release: a patch release on an earlier line, or a re-run of an old tag, leaves them where they are. Pin an
exact version tag (for example rmyndharis/openwa:0.31.0) for reproducible deploys and a known
rollback target. Since v0.28.0 the production image omits typescript and ts-node (saving about 40 MB while keeping typeorm for the :prod migration scripts), and since v0.29.0 the linux/amd64 image ships Chrome for Testing 157 (157.0.8103.78 in v0.30.1 through v0.30.3, 157.0.8103.50 in v0.30.0, 157.0.8103.38 in v0.29.0 and v0.29.1) and since v0.31.0 Chrome for Testing 158 (158.0.8127.36). The repo's bundled openwa-api service builds the image
locally (build: { context: ., dockerfile: Dockerfile }); if you followed the git clone path
above, either swap the image: line for that same build: block, or pull the published image
instead of cloning. The Traefik labels and expose block are identical either way. The image is
also mirrored to GitHub Container Registry (ghcr.io/rmyndharis/openwa) if you prefer it.
services:
openwa:
image: rmyndharis/openwa:latest # or: build: { context: ., dockerfile: Dockerfile }
restart: unless-stopped
# Shutdown budget: see "Allow shutdown to finish" below
stop_grace_period: 75s
volumes:
# API keys, databases and session auth
- openwa-data:/app/data
expose:
- "2785" # internal only — no host port mapping when Traefik is on this network
networks: [proxy]
labels:
- traefik.enable=true
- traefik.http.routers.openwa.rule=Host(`api.example.com`)
- traefik.http.routers.openwa.entrypoints=websecure
- traefik.http.routers.openwa.tls.certresolver=le
- traefik.http.services.openwa.loadbalancer.server.port=2785
networks:
proxy:
external: true
volumes:
openwa-data:
# Pinned by the repository's docker-compose.yml.
# Keep it, or Compose creates a new volume
name: openwa_openwa-data
Without the volumes entry, /app/data is the container's writable layer. It survives docker restart but not docker compose down, or an image update followed by up -d, and with it go main.sqlite (every API key), the session auth (every number scans its QR again) and, on SQLite, the data database. See Persist data with volumes for what the volume holds. Keep the name: line: without it Compose prefixes the volume with the project name and creates a new, empty volume instead of the openwa_openwa-data that the repository's docker-compose.yml uses. This service takes the place of the bundled openwa-api, so stop that stack first: two containers on one data volume are the case the warning at the top of this page rules out.
A dashboard stuck on "Connecting…" while localhost is healthy almost always points to the
proxy hop, not the app. Since all three surfaces share :2785, a choked upstream takes them
all down at once.
Cloudflare Tunnel
If your host is behind NAT, on a home network, or otherwise unreachable from the public
internet, you can replace the reverse proxy with a Cloudflare Tunnel
(cloudflared). The tunnel opens a long-lived outbound connection to Cloudflare, so no
inbound ports need to be opened and no public IP is required. WebSocket upgrades for the
Socket.IO channel are forwarded natively. See Cloudflare Tunnel
for the full setup (host install and Docker sidecar), the OpenWA environment to set, and the
free-plan limits to be aware of.
Expose or hide Swagger in production
OpenWA serves interactive API docs (Swagger UI) at /api/docs, controlled by ENABLE_SWAGGER:
ENABLE_SWAGGER=true # expose the docs at /api/docs
ENABLE_SWAGGER=false # disable on a publicly exposed deployment
Swagger is convenient during integration but publishes your full API surface. When
ENABLE_SWAGGER is unset it is on outside production and off under NODE_ENV=production, which
the runtime image sets itself, so a production deployment has to opt in with
ENABLE_SWAGGER=true. Only the exact strings true and false are accepted: a blank
value counts as unset, and any other value fails boot (v0.24.0+). On an internet-facing
deployment that does not set NODE_ENV=production, set ENABLE_SWAGGER=false explicitly,
or restrict /api/docs at the reverse proxy.
Wire up health checks
All health endpoints live under the /api prefix, require no API key, and are exempt from
rate limiting — point your load balancer and orchestrator at them directly.
| Endpoint | Purpose | Status codes |
|---|---|---|
GET /api/health | Basic check: returns status and timestamp; version only for a caller with a valid API key (v0.19.0+) | 200 |
GET /api/health/live | Liveness — static ok; a transient dependency outage does not fail it, so the orchestrator won't kill a recovering pod | 200 |
GET /api/health/ready | Readiness — probes both databases and returns 503 while draining during graceful shutdown | 200 / 503 |
Use /api/health/live for liveness probes and /api/health/ready for readiness and load
balancer checks. The bundled Compose file already wires /api/health/ready into the container
healthcheck (interval 30s, timeout 10s, 3 retries, 30s start period):
curl -i http://localhost:2785/api/health/ready
HTTP/1.1 200 OK
content-type: application/json
{"status":"ok","details":{"mainDatabase":{"status":"up"},"dataDatabase":{"status":"up"}}}
A 503 here means a database probe failed or the process is draining during shutdown — the
orchestrator should stop routing traffic until it returns 200. Since v0.28.0 /api/health/ready shares one in-flight database probe across concurrent callers and reuses the result for 1 second (except during shutdown, which answers 503 immediately), so overlapping readiness checks from a load balancer and container healthcheck do not multiply database queries.
Since v0.26.0 the HTTP port opens after at most 60 s of plugin restore, so plugins whose backends are down no longer keep the port closed long enough to fail the health checks into a restart loop; before, the port stayed closed until every enabled plugin was restored. Plugins still restoring then finish in the background. Until the restore has finished with a plugin, the hooks it owns (a send moderation veto, for one) do not run, enabling, disabling, updating, uninstalling or reinstalling it answers 409, and an ingress route of it with a response contract answers 503 with Retry-After; other deliveries are held and dispatched once the restore has finished with it. Do not rely on a plugin veto while a plugin is still restoring after a boot with slow plugins.
Allow shutdown to finish
Both bundled Compose files use stop_grace_period: 75s; the Helm chart uses terminationGracePeriodSeconds: 75. With default settings, shutdown first marks readiness 503 and waits 3 s, then allows up to 67 s for teardown before exiting with status 1, leaving 5 s before the orchestrator kills it. Increase the deployment grace by any excess of SHUTDOWN_DELAY_MS over 3000 ms and WEBHOOK_SHUTDOWN_DRAIN_MS over 5000 ms. A blocking SQLite lock can still prevent these timers running. Since v0.27.0 a second SIGTERM or SIGINT arriving within 1 s of the first is ignored as a duplicate signal delivery while graceful shutdown continues; a second stop signal arriving 1 s or more after the first forces an immediate exit with status 1. Since v0.28.0 SIGHUP triggers the same graceful shutdown drain as SIGTERM and SIGINT, while SIGQUIT, SIGABRT, and bare SIGUSR2 are left unhandled.
Once teardown starts, API requests answer 503 with Connection: close, including /api/infra/health. The /api/health probes, dashboard HTML, and CORS preflights remain available; use /api/health/live for liveness and /api/health/ready to remove traffic. A new /events handshake can still connect until HTTP close. Session starts are refused as soon as shutdown begins.
Ingress workers stop taking jobs at shutdown; webhook workers stop when teardown begins. Each waits at most 10 s for running jobs. Unfinished jobs can run again on the next start, so webhook receivers must deduplicate X-OpenWA-Idempotency-Key and plugin ingress handlers must deduplicate delivery ids. Plugin disable hooks share one 10 s shutdown budget.
A custom container spec starting as root with all capabilities dropped needs KILL alongside CHOWN, DAC_OVERRIDE, FOWNER, SETGID, and SETUID. Without it, the init process cannot forward the stop signal after the privilege drop, and the container reaches its kill deadline with exit 137. The bundled specs include it.
Optional: Prometheus metrics
OpenWA exposes Prometheus-format metrics at GET /api/metrics, but the endpoint is disabled
by default (returns 404) until you set METRICS_TOKEN. Once set, scrapers must send
Authorization: Bearer <token>; the token is separate from your API key. Since v0.23.7 a
client that sends 10 missing or wrong tokens within a minute gets 429 until that window
slides, even if its next token is right. The endpoint serves
Prometheus text exposition format, not JSON, and since v0.11.0 it is part of the published
OpenAPI spec — see the metrics tag in the API Reference.
The token is a secret of your own. Since v0.26.0 the production boot guard refuses the placeholder
from .env.example and the known weak values it checks the other secrets against, such as test,
change-me and password, and the container exits naming METRICS_TOKEN (breaking); before, any
value was accepted. Unset keeps the endpoint disabled. Generate a token and paste the output as the value. Compose does not
run command substitution in .env, so writing $(...) there would make the literal text the token:
openssl rand -hex 32
METRICS_TOKEN=<the generated token>
# with the same token in the shell variable METRICS_TOKEN
curl -H "Authorization: Bearer $METRICS_TOKEN" \
http://localhost:2785/api/metrics
The exported series are openwa_up, the three process gauges openwa_process_uptime_seconds,
openwa_process_resident_memory_bytes, and openwa_process_heap_used_bytes,
openwa_stats_available, openwa_sessions_total, openwa_sessions_active,
openwa_sessions{status="..."}, openwa_messages_total{direction="outgoing"} and
openwa_messages_total{direction="incoming"}, and openwa_messages_failed_total.
openwa_webhook_delivery_failures_total has been exported since v0.8.11; v0.10.0 adds two
counters, openwa_session_reconnect_attempts_total and openwa_session_reconnect_loop_alerts_total.
Since v0.24.0 the scrape also carries the event-loop gauges openwa_event_loop_delay_p99_seconds
and openwa_event_loop_delay_max_seconds (the delay since the previous uncached scrape),
openwa_unhandled_rejections_total{kind} with kind set to other or page_context_lost, and
openwa_queue_jobs{queue,state} for each queue that is enabled and readable.
Also exported are openwa_sessions_restricted (sessions with an active account restriction, including passkey_required in v0.30.0+), openwa_send_pacing_refusals_total{reason}, and openwa_ingress_dedup_body_mismatches_total (v0.28.0+, incremented when an inbound integration delivery reuses a deliveryId with a different payload hash),
plus the deliberately unprefixed HTTP RED pair http_requests_total{method,route,status} and the
http_request_duration_seconds histogram (_bucket, _sum, _count), so a generic RED
dashboard or alert rule matches them without knowing anything about OpenWA. Since v0.28.0 http_requests_total records status="499" when a client closes the connection before the response is sent, 408 or 503 when the in-flight body budget drops a stalled body or sheds an over-budget upload, and route="(unmatched)" for requests that match no controller route. Not every series is
on every scrape: the database-derived session and message series are omitted entirely when the
data database cannot be read, which is what openwa_stats_available reports. Since v0.26.0 a scrape
waits at most 2 s for those statistics: a read that runs late is kept and served for up to 5
minutes, so the series can trail the database by that long, and they are omitted only when a read
failed or none is recent. The pacing and
HTTP families appear only once something has been recorded, so alert with absent() rather than
reading a missing series as zero. OpenWA exports no Node default (nodejs_*) or host metrics, so
scrape an external exporter (cAdvisor, node-exporter) for host signals.
Size the host
Sizing depends heavily on engine choice and message volume. The default whatsapp-web.js
engine spawns a Chromium instance per session (~300–500 MB RAM each); ENGINE_TYPE=baileys is
far lighter because it has no browser. Treat the table below as starting guidance and size up
from your own monitoring.
| Sessions | RAM | CPU | Disk |
|---|---|---|---|
| 1–5 | 2 GB | 2 cores | 20 GB |
| 5–10 | 4 GB | 4 cores | 50 GB |
| 10–20 | 8 GB | 8 cores | 100 GB |
| 20+ | 16 GB+ | 16+ cores | 200 GB+ |
The Compose file caps container memory via OPENWA_MEM_LIMIT (default 2g). Raise it for many
concurrent sessions:
OPENWA_MEM_LIMIT=8g docker compose up -d
The bundled Compose files also cap the container at 2048 processes (OPENWA_PIDS_LIMIT, default 2048). The repository sizes that at about 8 to 10 whatsapp-web.js sessions, because each session runs a multi-process Chromium: beyond that, a new session's Chromium is killed while it starts. Raise the variable for larger fleets and do not set -1, which removes the fork-bomb guard. It changes nothing on Baileys, which is a single process. The Helm chart sets no process cap.
Media bursts need separate headroom: INBOUND_MEDIA_CONCURRENCY (default 4) caps each session, and INBOUND_MEDIA_GLOBAL_CONCURRENCY (default 0, disabled) can bound all sessions together. Base64 adds about one third to downloaded payload size. Archive uploads can overlap without a global cap and hold base64 plus decoded bytes, with an additional readback in archive-only mode; slow S3 can grow that overlap. Inline webhook deliveries can also retain media while parked or backing off, up to about 1.3 GiB at the default queue limits. Lower the inline media caps or use QUEUE_ENABLED=true to move parked delivery payloads to Redis. The bundled Compose files do not forward QUEUE_ENABLED from .env: turn the queue on with the Enable BullMQ Queue System switch in the Redis card of Dashboard → Infrastructure (it appears once Redis is enabled), which saves it to data/.env.generated, or forward it in a docker-compose.override.yml. MESSAGE_INLINE_MEDIA=archive saves storage after archiving, not burst memory. A send by url needs headroom too: it holds the whole downloaded body in memory, at least twice its size at the peak and, on whatsapp-web.js, more while the page call that carries it is in flight, so size the container memory for the number of large sends you run in parallel.
Cap the aggregate in-flight body budget
Alongside the per-request BODY_SIZE_LIMIT (default 25mb), v0.11.0 adds
INFLIGHT_BODY_BUDGET_BYTES — an aggregate budget over the request-body bytes in flight across
all connections, defaulting to 4× BODY_SIZE_LIMIT. A request's Content-Length is reserved
at admission; a request that would push the total over budget gets a transient 503 with
Retry-After: 1 and Connection: close instead of being buffered. A sender that ships headers
and then goes silent is dropped after 15 seconds without new body bytes. Since v0.28.0 a request's reserved bytes are released as soon as the request body finishes reading rather than waiting for the response to finish, so slow downstream engine calls no longer hold upload budget after the body has arrived.
No single caller may hold more than half of that budget in flight, so one heavy uploader cannot
starve the rest. Since v0.24.0 a request that carries an active API key is charged to that key,
however many addresses use it; before, every request was charged to its client address with the
same half-budget limit (v0.21.0+). Every other request (no key, an unknown, expired or
address-refused key, and ingress deliveries from outside providers) shares an unkeyed pool of a
quarter of the budget, never less than two BODY_SIZE_LIMIT bodies, and each client address holds
at most half of that pool. The address is the one resolved through TRUSTED_PROXIES, so behind a
proxy that is not listed there every unkeyed request counts as one client. Since v0.23.6 an IPv6
client is counted on its /64, so unkeyed uploaders on one IPv6 network share one half. A body whose
declared size the budget, the caller's share or the pool could never admit is refused with 413
and no Retry-After, because retrying cannot help.
The operational consequence: many concurrent near-limit uploads can now transiently 503 even
when each one is individually under BODY_SIZE_LIMIT. If your workload batches large media
uploads, raise the budget so the aggregate fits the concurrency:
INFLIGHT_BODY_BUDGET_BYTES=524288000 # 500 MB aggregate, in bytes
Deploy with Helm (Kubernetes)
Since v0.13.0, the repository ships an official Helm chart under charts/openwa/ for Kubernetes deployments. It is a single-replica StatefulSet with a PVC for /app/data (session auth, the main database, media, and plugins), the same hardening as the Docker image (read-only rootfs, dropped capabilities, writable emptyDir at /tmp), free-form env/secretEnv maps covering every variable in .env.example, and optional Ingress, PodDisruptionBudget, and ServiceMonitor resources.
helm upgrade --install openwa ./charts/openwa \
--set secretEnv.API_MASTER_KEY="$(openssl rand -base64 32)"
Upgrade an existing release with helm upgrade openwa ./charts/openwa --reset-then-reuse-values (Helm 3.14+), or supply your reviewed values with -f values.yaml. Plain --reuse-values retains the old 45 s grace and capability list without KILL. Explicitly set values still win; update any old overrides and any pinned image.tag.
The startup probe defaults to periodSeconds: 5 and failureThreshold: 60 (about 295 s until the last failed check). v0.25.0 builds three message indexes on first boot, and an upgrade from before v0.24.0 builds that release's two as well. The first boot on v0.26.0 also converts legacy message types in one migration statement while the port stays closed (about 60 s per million legacy rows on PostgreSQL), and on SQLite it checks the message search index against all stored text and rebuilds it when they differ; before, the conversion ran at every boot. A large table may exceed that budget. Raise startupProbe.failureThreshold or run migrations before startup.
For a non-root start, the chart accepts podSecurityContext with runAsUser, runAsGroup, and fsGroup set to 997, plus runAsNonRoot: true and fsGroupChangePolicy: OnRootMismatch. Remove the default added capability list with containerSecurityContext.capabilities.add: null; the volume must be writable by that identity.
Datastores are not bundled — point env at your own PostgreSQL/Redis/MinIO, or stay on the SQLite default. Keep replicaCount: 1: OpenWA is a single-process application. The session lease stops two pods from starting the same session, but each pod keeps its own main.sqlite, so a key created, revoked or narrowed on one pod is unchanged on the others, and the WebSocket rate-limit buckets, reconnect timers and in-flight bulk batches are process-local. The chart's values.yaml comments and README.md document every knob.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Container exits immediately, logs mention a placeholder secret or a 32-character minimum | A set API_MASTER_KEY is a placeholder or under 32 characters (v0.19.0+), DATABASE_PASSWORD on postgres or the S3 keys on s3 are empty or placeholders, a REDIS_PASSWORD is a known placeholder (an empty one is allowed), a METRICS_TOKEN is a placeholder or known weak value (v0.26.0+; unset is allowed), or ALLOW_DEV_API_KEY=true. An unset or empty API_MASTER_KEY is not a cause | Set real values of sufficient length, or leave API_MASTER_KEY unset so first boot generates a key. |
postgres profile container won't initialize | DATABASE_PASSWORD is empty | Set a non-empty DATABASE_PASSWORD; the Postgres image refuses an empty password. |
| Browser requests blocked from the dashboard | CORS_ORIGINS=* in production | Set explicit origins; the wildcard is refused outside development. |
Dashboard stuck on "Connecting…" but /api/health returns 200 on the host | Double network hop (host publish and proxy) exhausting connections | Route only through the proxy; expose the port internally instead of publishing it. |
Uploads intermittently return 503 with Retry-After | Concurrent bodies exceed the aggregate in-flight budget, or the caller's share of it: a key's half (v0.24.0+), or before that an address's half (v0.21.0+) | Retry (clients should honor Retry-After); raise INFLIGHT_BODY_BUDGET_BYTES if it persists. |
Boot fails with PostgreSQL data connection is not on UTC (v0.23.6+) | A connection pooler drops the connection's SET TIME ZONE 'UTC', or a server-side default overrides it | Run ALTER DATABASE "<database>" SET TimeZone='UTC', or let the statement through the pooler. Since v0.27.0 the pool applies statement_timeout, TimeZone='UTC' and search_path as SQL statements on each new connection instead of startup packet options, so PgBouncer in session pooling mode works without ignore_startup_parameters; transaction pooling remains unsupported because boot migrations and background trigram index builds use session-level advisory locks. |
| "Permission denied" writing to a bind-mounted data dir | The container was started as a non-root user (--user, or user: in Compose) that cannot write the host directory; a default root start re-owns /app/data itself | With --user 997:997 on a Docker daemon that runs as root: sudo chown -R 997:997 ./data. |
Boot warns that the local media directory could not be made owner-only (0700) (v0.31.0+) | The gateway could not change the mode of the media directory, for example because it does not own it (a bind mount or volume owned by another user), and a file in it written with a loose mode stays readable by other users | Own the directory as the gateway's user (uid 997 in the image) and restart, or restrict it from outside: a stricter mode or ACL on the mount, or a parent directory only that user can enter. |
Media sends above about 750 KB of file return 413 through nginx | nginx refuses request bodies above client_max_body_size, 1m by default, before OpenWA sees them | Set client_max_body_size in the server or location block to at least BODY_SIZE_LIMIT (25mb by default), as in the nginx example. |
| Session stuck at "authenticating" after scanning the QR | whatsapp-web.js picked an incompatible WhatsApp Web build | Pin WWEBJS_WEB_VERSION to a known-good version, or raise WWEBJS_AUTH_TIMEOUT_MS on slow hosts. A pin can fail to take. Since v0.23.6 a session that reaches ready logs the build its page runs (web_version_running), or a warning naming both builds when that is not the pinned one (web_version_pin_not_applied). Since v0.29.0 a registry build whose HTML is WhatsApp's logged-out landing page is rejected (web_version_html_rejected), stepping back up to 3 older settled builds on auto/latest (from the same registry read without a second fetch since v0.29.1) or falling back to WhatsApp's live page (web_version_html_unavailable). A session still stuck at "authenticating" logs web_version_running only once it connects. |
Session stuck at "authenticating" after scanning the QR, in the container image with WWEBJS_WEB_VERSION=off or the wa-version registry unreachable (up to v0.23.5) | With no pin, whatsapp-web.js wrote its local HTML cache into the unwritable app directory | Upgrade to v0.23.6, where an unpinned session caches nothing to disk, or pin WWEBJS_WEB_VERSION to an exact build. |
Boot or migration CLI fails with Cannot read <path>: <reason> (v0.28.0+) | .env or data/.env.generated exists on disk as a directory (for example a single-file bind mount whose host file was missing) or cannot be read by the runtime user | Make the file readable by uid 997 (or the user running the CLI), or replace the directory with a regular file. |
For more, see Troubleshooting & FAQ.
Next steps
- Configuration reference — every environment variable, with defaults.
- Migration guide — upgrades, backups, and moving data between hosts.
- Horizontal scaling — why OpenWA runs one instance per session volume.
- Authentication — managing API keys and access control.