Docker

Use Docker to run the Easy API with its browser dependencies in one container. You will need Docker and a writable ./sessions directory for the WhatsApp profile. Choose a long, random string for your API key and replace your-secure-key in the examples with it. These steps start open-wa 5.1.0 and make the API available on your local machine.

The commands pin the Docker image digest and the npm package installed at startup. They also pass --session-id, --host, and --port explicitly so the session and listener use the requested values.

Run the Easy API containerCopy Anchor Link

Start with this baseline. It publishes port 8080 on loopback, names the session sales, persists its browser profile in ./sessions/sales, and sets the API key for protected requests:

docker run --name openwa-sales --init \
  -p 127.0.0.1:8080:8080 \
  -v "$PWD/sessions:/sessions" \
  -e W_A_V=5.1.0 \
  -e WA_PORT=8080 \
  -e WA_HOST=0.0.0.0 \
  -e WA_SESSION_ID=sales \
  -e WA_USER_DATA_DIR=/sessions/sales \
  -e WA_API_KEY="your-secure-key" \
  openwa/wa-automate:latest@sha256:d31f5a8f59c4890a302294e9834a25f217a973d80339896ef74cf3d35d903cb3 \
  --session-id sales --host 0.0.0.0 --port 8080

Complete authentication in the terminal, then check readiness from the host:

curl http://localhost:8080/health

/health is public and can include QR and operational details, so the loopback binding is important; status: "ok" confirms the HTTP process is live, while connected: true and session.ready: true confirm WhatsApp readiness.

The mounted ./sessions directory contains authentication state. Keep it private and do not remove it when recreating the container.

Version pins and image sourceCopy Anchor Link

Docker Hub currently uses a moving latest tag, so the commands use the immutable OCI digest shown in each image reference. The image startup script otherwise installs npm latest; W_A_V=5.1.0 selects the published npm release used by these examples. See the Docker Hub image and its pinned startup script. The image declares Node.js 23.8.0, which is above v5.1.0's 22.21.1 minimum.

Environment variables and secretsCopy Anchor Link

The runtime configuration loader consumes WA_* names. WA_API_KEY configures the Easy API key, WA_SESSION_ID names the session, and WA_USER_DATA_DIR selects the profile; see Configuration and CLI for supported settings. OPENWA_API_KEY, PORT, and SESSION_ID are not automatic aliases.

For a local .env file, keep it outside version control and load it explicitly with Docker:

WA_PORT=8080
WA_HOST=0.0.0.0
WA_SESSION_ID=sales
WA_USER_DATA_DIR=/sessions/sales
WA_API_KEY=your-secure-key
W_A_V=5.1.0

docker run --name openwa-sales --init \
  -p 127.0.0.1:8080:8080 \
  -v "$PWD/sessions:/sessions" \
  --env-file .env \
  openwa/wa-automate:latest@sha256:d31f5a8f59c4890a302294e9834a25f217a973d80339896ef74cf3d35d903cb3 \
  --session-id sales --host 0.0.0.0 --port 8080

The env file supplies the same values as the baseline. The command arguments set the session and listener explicitly; Docker forwards requests from loopback to the container. Keep .env out of version control and inject these values through your platform's secret store in production.

Docker ComposeCopy Anchor Link

Compose keeps the port, profile mount, environment, and process init together:

services:
  openwa:
    image: openwa/wa-automate:latest@sha256:d31f5a8f59c4890a302294e9834a25f217a973d80339896ef74cf3d35d903cb3
    init: true
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./sessions:/sessions
    environment:
      WA_PORT: "8080"
      WA_HOST: "0.0.0.0"
      WA_SESSION_ID: sales
      WA_USER_DATA_DIR: /sessions/sales
      WA_API_KEY: ${WA_API_KEY:?Set WA_API_KEY in .env before starting}
      W_A_V: 5.1.0
    command: ["--session-id", "sales", "--host", "0.0.0.0", "--port", "8080"]
    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://localhost:8080/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

Start it with the key supplied from the shell or an ignored .env file:

WA_API_KEY="your-secure-key" docker compose up

The Compose health check only confirms an HTTP response; it does not confirm WhatsApp authentication.

--init and browser resourcesCopy Anchor Link

Use --init when running the container directly. The browser creates child processes, and an init process reaps them when they exit. Give the container enough memory and CPU for WhatsApp Web, especially when running multiple sessions.

On constrained hosts, keep the runtime's normal browser arguments and add --shm-size=1gb to the launch command to give Chrome more shared memory. A single session typically needs 700 MB–1 GB of RAM. See browser launch troubleshooting if Chrome fails to start or exits unexpectedly.

Verify persistence after a restartCopy Anchor Link

After the first successful authentication:

1. Stop and remove only the container, leaving ./sessions in place:

   Copy Text

   docker stop openwa-sales
   docker rm openwa-sales

2. Run the same baseline command again with the same WA_SESSION_ID and WA_USER_DATA_DIR.

3. Check /health until connected: true and session.ready: true.

The runtime should reuse /sessions/sales without a new QR prompt. If a new QR appears, inspect the host mount and the profile path before deleting any session data.

Use the image as a base for your own codeCopy Anchor Link

If you need the browser/runtime dependencies but want your own entrypoint:

FROM openwa/wa-automate:latest@sha256:d31f5a8f59c4890a302294e9834a25f217a973d80339896ef74cf3d35d903cb3
ENTRYPOINT []

# copy your project and run your own command afterwards

Keep business logic in your service and call the Easy API or consume events from it. Embedded Node.js code that owns the browser belongs in Custom code.

Production notesCopy Anchor Link

Keep the API port private, persist the session profile, inject secrets at runtime, and configure WA_API_KEY for protected API methods. The API key does not replace WhatsApp authentication.

v4 archiveCopy Anchor Link

The npm v4 archive remains available for existing v4 applications:

npx @open-wa/wa-automate@4.76.0

Docker Hub does not provide a matching versioned 4.76.0 image tag.

Keep v4 configuration and session profiles separate from a v5 deployment. New npm examples on this site target 5.1.0.