Skip to main content
Version: v0.31.0

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.

Prerequisites
  • 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.
Run one instance per session volume

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
ProfileAddsRequires
postgresPostgreSQL 16DATABASE_TYPE=postgres, DATABASE_HOST=postgres, DATABASE_PORT=5432, DATABASE_USERNAME=openwa, a non-empty DATABASE_PASSWORD
redisRedis 7REDIS_ENABLED=true, REDIS_HOST=redis
minioMinIO (S3-compatible)STORAGE_TYPE=s3, S3_ENDPOINT=http://minio:9000, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY
fullAll of the aboveThe 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.

VariablePurposeProduction guidance
NODE_ENVRuntime modeSet 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_KEYMaster API keySet 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_TYPEDatabase backendsqlite (default) or postgres.
STORAGE_TYPEMedia storage backendlocal (default) or s3.
ENGINE_TYPEWhatsApp enginewhatsapp-web.js (default, Chromium-based) or baileys (browser-free). Leave blank to let the dashboard's Infrastructure → Engine setting decide.
SESSION_DATA_PATHWhere WhatsApp auth state is storedDefaults to /app/data/sessions in the container.
TZProcess time zoneThe 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_ORIGINSAllowed browser originsThe wildcard * is refused in production. Set explicit origins, e.g. https://dashboard.yourdomain.com.
ENABLE_SWAGGERInteractive API docs at /api/docsSee Swagger in production.
Never commit secrets

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) and openwa.sqlite (user data, when DATABASE_TYPE=sqlite).
  • Local media — when STORAGE_TYPE=local, under data/media (STORAGE_LOCAL_PATH). Since v0.31.0 that directory is owner-only: the gateway sets it 0700 at every boot when it owns it, and writes new directories and files 0700 and 0600. 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 as openwa). Files written earlier keep their mode but sit under the 0700 directory. A directory the gateway does not own keeps its mode, and the boot logs a warning while that mode lets other users in. With STORAGE_TYPE=s3 the 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 0600 in a 0700 data/exports, and the next boot closes a data/exports an 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.

Back up session auth before any maintenance

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:

  1. Route over the Docker network — don't also publish the host port. If OpenWA both publishes 2785:2785 to the host and is routed through Traefik, every request makes an extra hop through Docker's docker-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 return 504 together while curl …/api/health/ready on the host still returns 200. Put the service on the proxy's shared network and expose the port internally instead of publishing it.
  2. 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.

One port, shared fate

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.

EndpointPurposeStatus codes
GET /api/healthBasic check: returns status and timestamp; version only for a caller with a valid API key (v0.19.0+)200
GET /api/health/liveLiveness — static ok; a transient dependency outage does not fail it, so the orchestrator won't kill a recovering pod200
GET /api/health/readyReadiness — probes both databases and returns 503 while draining during graceful shutdown200 / 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.

SessionsRAMCPUDisk
1–52 GB2 cores20 GB
5–104 GB4 cores50 GB
10–208 GB8 cores100 GB
20+16 GB+16+ cores200 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​

SymptomCauseFix
Container exits immediately, logs mention a placeholder secret or a 32-character minimumA 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 causeSet real values of sufficient length, or leave API_MASTER_KEY unset so first boot generates a key.
postgres profile container won't initializeDATABASE_PASSWORD is emptySet a non-empty DATABASE_PASSWORD; the Postgres image refuses an empty password.
Browser requests blocked from the dashboardCORS_ORIGINS=* in productionSet explicit origins; the wildcard is refused outside development.
Dashboard stuck on "Connecting…" but /api/health returns 200 on the hostDouble network hop (host publish and proxy) exhausting connectionsRoute only through the proxy; expose the port internally instead of publishing it.
Uploads intermittently return 503 with Retry-AfterConcurrent 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 itRun 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 dirThe 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 itselfWith --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 usersOwn 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 nginxnginx refuses request bodies above client_max_body_size, 1m by default, before OpenWA sees themSet 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 QRwhatsapp-web.js picked an incompatible WhatsApp Web buildPin 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 directoryUpgrade 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 userMake 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​