Skip to main content
Version: v0.31.0

Install OpenWA

This guide installs a running OpenWA instance — the REST API plus the bundled web dashboard — and verifies it with a health check. Pick one of two paths:

  • Docker Compose — recommended. One command, no Node toolchain, Chromium bundled in the image.
  • From source — when you want hot reload or to hack on OpenWA itself. Needs Node.js 22.19 or newer.

Both paths serve everything on port 2785: the API under /api and the dashboard at /. Interactive Swagger docs at /api/docs come up on a source run and on the quick-start docker-compose.dev.yml, both of which are non-production until a copied .env.example sets NODE_ENV=production (see Set your environment). The published image and the full docker-compose.yml default to NODE_ENV=production, where /api/docs stays off until you set ENABLE_SWAGGER=true.

Prerequisites
  • A 64-bit Linux, macOS, or Windows host (linux/amd64 or linux/arm64).
  • A phone with WhatsApp installed — you scan a QR code to connect a session later.
  • For the Docker path: Docker Engine 20.10+ with the Compose v2 plugin (docker compose). docker-compose.yml needs Compose 2.20.0 or newer, because it uses depends_on.required; check with docker compose version. New to Docker? See Install Docker.
  • For the source path: Node.js 22.19 or newer and npm. That is the package's engines floor, set by the bundled undici; below it npm install warns with EBADENGINE (and fails outright under engine-strict), and a dependency may then call an API the older runtime lacks. On Linux with glibc, the prebuilt sharp and better-sqlite3 binaries require glibc 2.34 or newer (Ubuntu 22.04+, Debian 12+, RHEL/Alma/Rocky 9+); on an older distribution npm install falls back to compiling from source or fails at startup with GLIBC_2.xx not found. The published Docker image (node:22-slim) carries its own runtime and is unaffected.

Choose your path​

Prerequisites in detail​

RequirementDocker ComposeFrom source
RuntimeDocker Engine + Compose v2 (2.20.0 or newer for docker-compose.yml)Node.js 22.19 or newer, npm
WhatsApp engineBundled (whatsapp-web.js default)Bundled; whatsapp-web.js needs a Chromium binary, baileys needs none
ChromiumIncluded in the imageAuto-downloaded by Puppeteer, or point PUPPETEER_EXECUTABLE_PATH at a system one
RAM~2 GB for the default engine (a headless Chromium per session)Same
Disk~2 GB for the image + session data~2 GB for node_modules + session data
Which engine, and why RAM matters

OpenWA ships two WhatsApp engines, selected by ENGINE_TYPE. The default whatsapp-web.js drives a headless Chromium per session (heavier, ~2 GB RAM guideline). baileys is a WebSocket client with no browser (much lighter). You can switch later in Configuration; leave it unset for now to use the default.

OpenWA ships two Compose files. Use the one that matches your goal:

FileWhat it isDatabaseUse it when
docker-compose.dev.ymlSingle-container quick start (production image, local SQLite, bind-mounted ./data)SQLiteYou want OpenWA up in one command
docker-compose.ymlCore API plus optional backing services behind Compose profilesSQLite (default), PostgreSQL optionalYou want PostgreSQL, Redis, or S3-compatible storage

Neither file runs a separate dashboard container — the dashboard SPA is built into the API image and served by the same process on port 2785.

Fastest: run the prebuilt image (no build)​

The clone-and-Compose paths below build the production image from source the first time you start them — several minutes that download and install Chromium. If you only want to run OpenWA, skip that entirely. The official multi-arch image (linux/amd64 and linux/arm64) is published to Docker Hub, so a docker pull is seconds, not minutes. This path needs only Docker — no Compose, no clone, no Node toolchain.

mkdir -p data
docker run -d --stop-timeout 75 --restart unless-stopped \
--name openwa-api -p 127.0.0.1:2785:2785 \
-v "$(pwd)/data:/app/data" rmyndharis/openwa:latest

The same image is mirrored to GitHub Container Registry (ghcr.io/rmyndharis/openwa) if you prefer to pull from there.

That runs with zero-config defaults — SQLite for the database, local storage for media. The schema initializes automatically on first boot; there is nothing to set. The single ./data bind mount persists everything — database, sessions, media, and your API key. Since v0.31.0 the media directory under it (data/media) is owner-only, so on Linux a host process that reads it as another user, such as a static file server, is refused (see Persist data with volumes).

-p 127.0.0.1:2785:2785 publishes the port on the loopback address, as both Compose files do (see Bind address and TLS); -p 2785:2785 without the address publishes it on every host address. --restart unless-stopped is the restart policy both Compose files set: Docker restarts the container if it exits or if the Docker daemon restarts, but not after you stopped it yourself. Linked sessions start again after such a restart only if AUTO_START_SESSIONS=true is set, for example by adding -e AUTO_START_SESSIONS=true to the command; the gateway leaves it off by default. Without it, start each one again with POST /api/sessions/{sessionId}/start. Since v0.30.3 the boot log says how many previously linked sessions that default left disconnected (action=auto_start_disabled).

On first boot OpenWA generates a random admin key and writes it to data/.api-key inside that bind-mounted directory. You need it for every authenticated request. It is written owner-only (mode 0600) as the container's own user, so on Linux a host cat is refused. Read it through the container, which works the same on every platform:

docker exec openwa-api cat /app/data/.api-key

You can also view and create keys in the dashboard at http://localhost:2785. Quick start exports it and makes its first authenticated call.

To pin an exact version instead of tracking latest, use the version tag:

docker run -d --stop-timeout 75 --restart unless-stopped \
--name openwa-api -p 127.0.0.1:2785:2785 \
-v "$(pwd)/data:/app/data" rmyndharis/openwa:0.31.0

Update later. Back up first, pull the new image, stop the old container with a 75 s timeout, remove it, and re-run the same command. Your data survives in ./data. Read the v0.24.0 and v0.25.0 upgrade notes, the v0.26.0 upgrade notes, the v0.27.0 upgrade notes, the v0.28.0 and v0.29.0 upgrade notes, and the v0.31.0 upgrade notes before upgrading an existing deployment. On linux/amd64, v0.29.0 moves the image's Chrome for Testing from 156 to 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, after v0.26.0 moved it from 153 to 156), and v0.31.0 moves it to 158 (158.0.8127.36). On linux/amd64, rolling back across a browser major (from v0.31.0 to v0.30.3 or earlier, from v0.29.0 through v0.30.3 to v0.28.0 or earlier, or from v0.26.0-v0.28.0 to v0.25.0 or earlier) deletes the stored whatsapp-web.js logins unless data/sessions/ is restored from a backup taken before the first start on the newer browser. The linux/arm64 image runs the chromium Debian ships when the image is built, whose major can differ between releases. Baileys sessions are unaffected.

If you later moved this instance to PostgreSQL (for example from the dashboard's Infrastructure page), the database lives outside ./data: take a backup of it before you run these commands. When the gateway (a -e TZ=... on this command) or the database server ran outside UTC, moving to v0.23.6 or later from an earlier release also needs the fix in PostgreSQL deployments that ran outside UTC, applied after stopping and removing the container and before docker run:

docker pull rmyndharis/openwa:latest
docker stop -t 75 openwa-api
docker rm openwa-api
docker run -d --stop-timeout 75 --restart unless-stopped \
--name openwa-api -p 127.0.0.1:2785:2785 \
-v "$(pwd)/data:/app/data" rmyndharis/openwa:latest

Then confirm it answers — see Verify the install below.

Since v0.23.6 the dashboard sidebar shows an admin a link to the release notes when a newer release is published. The gateway asks api.github.com for it and caches the answer for six hours; where that outbound request is not wanted, add -e UPDATE_CHECK_ENABLED=false to the docker run command (see Configuration).

When to use the Compose files instead

The docker-compose.dev.yml and docker-compose.yml paths below build from source on first run, and they remain the way to add PostgreSQL, Redis, or S3-compatible storage behind Compose profiles. Building from source is only needed when you want to modify OpenWA itself — see Option B: From source.

Quick start (single container)​

Clone the repository, check out a release tag and bring up the quick-start stack. It builds the production image and runs it against a local SQLite database with ./data bind-mounted for persistence. The default branch holds whatever has merged since the last release, so build a tag:

# <release> is the release to run, see https://github.com/rmyndharis/OpenWA/releases
git clone --branch v<release> https://github.com/rmyndharis/OpenWA.git && cd OpenWA \
&& docker compose -f docker-compose.dev.yml up -d

The first build takes a few minutes (it installs Chromium). When it finishes, open:

SurfaceURL
Dashboardhttp://localhost:2785
REST APIhttp://localhost:2785/api
Swagger UIhttp://localhost:2785/api/docs

The dev compose sets AUTO_START_SESSIONS=true (v0.10.0+), so previously authenticated sessions restart automatically on compose up — no manual start calls after a container restart.

This is a smoke test, not hot reload

Despite the dev in its name, docker-compose.dev.yml runs the same production image — there is no source mount and no live reload. For a hot-reload development loop, use Option B: From source.

Full stack (PostgreSQL, Redis, storage)​

The main docker-compose.yml runs the core API on SQLite and local storage by default, and gates optional backing services behind Compose profiles:

# Core only — SQLite, local storage
docker compose up -d

# Add PostgreSQL
docker compose --profile postgres up -d

# Everything — PostgreSQL, Redis, and MinIO (S3-compatible storage)
docker compose --profile full up -d
ProfileAddsSelected by
postgresPostgreSQL 16DATABASE_TYPE=postgres
redisRedis 7 cache/queueREDIS_ENABLED=true (the queue also needs QUEUE_ENABLED=true, which on Compose you set in the dashboard under Infrastructure)
minioMinIO, S3-compatible storageSTORAGE_TYPE=s3
fullAll of the above—

docker compose up -d also starts openwa-docker-proxy, a Docker socket proxy that the dashboard's built-in datastore toggles reach the daemon through. It sits behind no profile, so it comes up with the core stack. Since v0.26.0 it no longer grants the INFO permission, nothing in OpenWA used it: GET /info through the proxy is refused, and a client of your own that reads it needs INFO: 1 on the proxy service. The proxy cannot limit what a container-create request asks for, so code running in the openwa-api container, an installed plugin included, can ask Docker to start a container with a host bind mount, which is root-equivalent on the host. Keep the proxy only if you use those toggles; if you never do, disable it with a docker-compose.override.yml that sets profiles: ['disabled'] on the docker-proxy service; orchestration then reports Docker unavailable and degrades gracefully.

Starting a profile only launches the container. You still point OpenWA at it with the matching environment variable — see Configuration for the full set.

On the Compose network those services answer to their service names, not localhost. Starting the postgres profile by hand needs DATABASE_TYPE=postgres, DATABASE_HOST=postgres, DATABASE_PORT=5432, DATABASE_USERNAME=openwa and your DATABASE_PASSWORD; Redis needs REDIS_ENABLED=true and REDIS_HOST=redis; MinIO needs STORAGE_TYPE=s3 and S3_ENDPOINT=http://minio:9000. The localhost values in the Configuration snippets are for a bare-metal run.

PostgreSQL, Redis, and S3 ship no default credentials

The postgres and minio images refuse to start with an empty password, and OpenWA's production boot guard rejects empty or placeholder secrets. Set DATABASE_PASSWORD (for PostgreSQL) and S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY (for MinIO) in your .env before starting those profiles.

The image can also start as uid/gid 997:997 with --user 997:997 (v0.24.0+), provided /app/data is already writable by that identity. The default entrypoint starts as root, fixes data ownership, then drops privileges. A custom root-start container that drops all capabilities needs CHOWN, DAC_OVERRIDE, FOWNER, KILL, SETGID, and SETUID so shutdown signals reach the app.

Set your environment​

The Compose files read configuration from a .env file in the project root. Copy the template and edit it before your first real start:

cp .env.example .env

For local testing you can leave the defaults, with one exception: the template sets NODE_ENV=production, so with a copied .env the quick-start docker-compose.dev.yml stack runs in production mode, and Swagger UI at /api/docs answers 404 until you set ENABLE_SWAGGER=true. Comment out the NODE_ENV line in .env to keep that stack on development. The most relevant knobs:

VariableDefaultPurpose
API_PORT2785Host port the API and dashboard bind to. Honored by both Compose files (the quick-start docker-compose.dev.yml since v0.23.7; before that it published 2785 whatever this said)
API_MASTER_KEYemptySet a strong key, or let OpenWA generate one on first boot
DATABASE_TYPEsqlitesqlite or postgres
STORAGE_TYPElocallocal or s3
ENGINE_TYPEunsetPin whatsapp-web.js or baileys; unset uses the dashboard default

If you do not set API_MASTER_KEY, OpenWA generates a random admin key on first boot and prints it in the startup banner (also written to data/.api-key). A key you set in API_MASTER_KEY is written to data/.api-key the same way, but since v0.28.0 the startup banner never prints an API_MASTER_KEY value in the logs. You need the key for every authenticated request, so grab a generated key now:

docker compose -f docker-compose.dev.yml logs openwa | grep -A1 -i "api key"

The quick-start stack's service is named openwa (its container is openwa-api), so you must pass both -f docker-compose.dev.yml and the openwa service name. On the full docker-compose.yml stack the service is openwa-api, so there you run docker compose logs openwa-api | grep -A1 -i "api key" instead. The banner prints the label and the key on two separate lines, which is why the match needs -A1.

The full key is in the banner only on the boot that created it. Every later boot prints a truncated fingerprint instead, so read the key from data/.api-key; the dashboard lists only each key's prefix.

Bind address and TLS​

Both Compose files and the docker run commands above publish the API on the loopback address 127.0.0.1 and serve plain HTTP. A docker run without the address, -p 2785:2785, publishes it on every host address, which Docker's port publishing documentation calls insecure by default. The same page notes that before Docker Engine 28.0.0, hosts on the same network segment as the machine can reach a port published to localhost.

Do not expose plain HTTP to the internet

The API key travels in the X-API-Key header in cleartext over plain HTTP. For any internet-facing deployment, put your own TLS reverse proxy (nginx, Caddy, a cloud load balancer, or a Kubernetes Ingress) in front and terminate TLS there. See Deployment for the full setup.

To reach the quick-start stack from another machine on a trusted network, set BIND_HOST=0.0.0.0 in your .env — but only behind that TLS proxy.

That stack runs the gateway with NODE_ENV=development unless .env or your shell sets NODE_ENV (a copy of .env.example sets production; see Set your environment). In development mode Swagger UI at /api/docs is served, the production secret checks are skipped, and a wildcard CORS origin is allowed, so widening the bind publishes that posture.

Before you do, set NODE_ENV=production in .env, or use the full docker-compose.yml, which defaults to production. Production mode also sends upgrade-insecure-requests in the dashboard's Content-Security-Policy: behind the TLS proxy this page requires it changes nothing, but a browser that reaches the dashboard over plain HTTP then upgrades the UI's scripts to https:// and the dashboard renders blank, as the gateway's boot warning says.

BIND_HOST only applies to docker-compose.dev.yml

Only the quick-start docker-compose.dev.yml reads BIND_HOST. The full docker-compose.yml hardcodes its port mapping to 127.0.0.1:${API_PORT:-2785}:2785 and ignores BIND_HOST, so setting it there has no effect. To expose that stack, edit the host side of its port mapping (and keep it behind the TLS proxy).

Using Podman instead of Docker?

Rootless Podman works if you start its socket and point DOCKER_HOST at it before running docker compose:

systemctl --user start podman.socket
systemctl --user enable podman.socket
export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock

Add the export line to your shell profile (~/.bashrc, ~/.zshrc) to make it permanent.

Now skip ahead to Verify the install.

Option B: From source​

Use this path for a hot-reload development loop or to modify OpenWA. It requires Node.js 22.19 or newer.

git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA

# Install dependencies. The postinstall hook also installs the dashboard's dependencies
# and applies OpenWA's patches to whatsapp-web.js and Baileys
npm install

Re-run npm install after every git pull, and never with --ignore-scripts: those patches live in node_modules, so a tree that skipped them keeps the bugs they fix. Since v0.23.6 one of them is what lets whatsapp-web.js send media on the WhatsApp Web builds rolled out on 2026-09-17: on whatsapp-web.js 1.34.7, which v0.23.6 through v0.30.3 ship, a tree without it fails every media send while text keeps working, and since v0.31.0 whatsapp-web.js 1.34.8 carries that fix itself. Since v0.30.0 another (patch-baileys-media-stream.js) wires Baileys v7 inbound media streams so an abandoned or cut-off download destroys its HTTP stream cleanly instead of terminating the gateway process with an unhandled stream error. Since v0.30.1 patch-baileys-status-ack.js acknowledges the top-level <status> stanza WhatsApp sends some Baileys accounts; left unacknowledged, it makes the server close the stream about 50 minutes after the connection opens, reported as Stream Errored (ack) (since v0.30.2 the patch also decodes a stanza shaped as a status message, so that status reaches the status list and the status.received webhook). Since v0.31.0 patch-baileys-event-buffer.js keeps what the library's event buffer drops within one buffering window: every group settings change after the first, a history sync's lid to phone pairs, and every answer to an event but the last. A patch that cannot apply does not fail the install, but each session logs the missing patch by name when its engine starts (see Troubleshooting). The exception is the patch that adapts whatsapp-web.js browser teardown to Puppeteer 25 (v0.26.0+): it is not best-effort, and a whatsapp-web.js source it does not recognise aborts the install.

OpenWA auto-generates its config on first run, so you can start without writing a .env file.

A source run is not bound to the loopback address. The API process accepts connections on every network interface, and the app reads no bind-address setting (BIND_HOST only configures docker-compose.dev.yml), so on a machine other people can reach, block port 2785 with a host firewall unless you mean to serve them.

On a machine other users can log in to, also start the gateway with TMPDIR set to a directory only its user can enter: Baileys stages the media of an upload, and whatsapp-web.js the output of a video sticker conversion, in the system temporary directory for the length of that send, as files created with the process umask, which other users can read under the common 022. The Docker image and the Helm chart keep /tmp inside the container and need nothing.

Run with hot reload​

npm run dev

This starts the API on port 2785 and the dashboard on the Vite dev server at port 2886 with hot reload:

SurfaceURL
Dashboard (Vite, hot reload)http://localhost:2886
REST APIhttp://localhost:2785/api
Swagger UIhttp://localhost:2785/api/docs
Dev dashboard port differs

In source-dev mode the dashboard runs separately on 2886. In every other mode (both Docker files, and the production build below) the dashboard is served by the API on 2785.

Run a production-style build locally​

To serve the bundled dashboard from the API on a single port, build the backend and the dashboard, then start:

npm run build # nest build — compiles the backend to dist/ only
npm run dashboard:build # builds the dashboard SPA into dashboard/dist
npm run start:prod

npm run build runs nest build and produces the backend in dist/ — it does not build the dashboard. The API only serves the SPA when dashboard/dist/index.html exists, which npm run dashboard:build (equivalently cd dashboard && npm run build) creates. Skip that step on a clean checkout and you get a working API at http://localhost:2785/api but a blank dashboard at http://localhost:2785.

With both builds done, the dashboard is at http://localhost:2785, the same as the Docker path.

Chromium for the default engine

The default whatsapp-web.js engine needs a Chromium or Chrome binary. Puppeteer downloads one during npm install; if it is not found at runtime, set PUPPETEER_EXECUTABLE_PATH to a system binary (for example /usr/bin/chromium). To avoid Chromium entirely, set ENGINE_TYPE=baileys.

Since v0.26.0 (Puppeteer 25) that downloaded browser is Chrome 156, where earlier releases downloaded Chrome 146, and since v0.31.0 (Puppeteer 25.17.0) it is Chrome 157. Back up SESSION_DATA_PATH (default data/sessions/) before the first start after updating, and restore it before going back to an earlier release. An explicit PUPPETEER_EXECUTABLE_PATH keeps selecting that browser.

Verify the install​

The health endpoints are public — no API key required — and live under the /api prefix. Run a basic check:

curl http://localhost:2785/api/health

A healthy instance returns 200 OK (the version field is disclosed only to requests carrying a valid API key, v0.19.0+):

{
"status": "ok",
"timestamp": "2026-06-26T10:15:00.000Z",
"version": "0.31.0"
}

Then confirm OpenWA is ready to serve traffic. The readiness probe checks that both the auth/audit and data databases respond:

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" }
}
}

If readiness returns 200, OpenWA is up and you can connect a WhatsApp account.

Troubleshooting​

SymptomCauseFix
curl: connection refused on 2785Container still building, or port not boundWait for the build to finish; check docker compose ps and docker compose logs openwa-api
/api/health/ready returns 503A database isn't reachable, or the app is shutting downInspect details in the body; for PostgreSQL, confirm DATABASE_PASSWORD is set and the postgres profile is up
PostgreSQL or MinIO container exits immediatelyMissing credentialsSet DATABASE_PASSWORD / S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY in .env — these images refuse empty secrets
Session stuck at "authenticating" after scanning the QRSlow first boot (WSL2, low-resource host)Raise WWEBJS_AUTH_TIMEOUT_MS (for example 120000) in .env
whatsapp-web.js engine fails to launch a browserNo Chromium found (source install)Set PUPPETEER_EXECUTABLE_PATH, or switch to ENGINE_TYPE=baileys
Port 2785 already in useAnother process holds the portOn either Compose file, change API_PORT in .env (before v0.23.7 the quick-start docker-compose.dev.yml ignored it: edit the host side of its '${BIND_HOST:-127.0.0.1}:2785:2785' mapping). From source, set PORT

For anything not covered here, see Troubleshooting.

Next steps​

  • Quick start — read your API key, link an account, and send your first message end to end.
  • Connect a session — scan the QR code and authenticate a WhatsApp account.
  • Configuration — set your API key, database, storage, and engine.