Skip to main content
Version: v0.7.6

Install Docker

This page is for people who have never installed Docker. It walks you through getting the docker command working on Windows, macOS, or Linux so the rest of these guides run as written. If you already have Docker, skip straight to Quick Start or Installation.

Which Docker do I need?
  • Windows and macOS — install Docker Desktop. It bundles the Docker engine, the CLI, and Compose v2 into one app.
  • Linux servers — install Docker Engine (the headless server install). Docker Desktop for Linux exists too, but Engine is the usual choice on a server.

Either way you get the same docker command OpenWA needs. Budget roughly 2 GB of RAM for the default whatsapp-web.js engine, which runs a headless Chromium per session.

Windows​

Docker Desktop on Windows runs containers through WSL2 (Windows Subsystem for Linux 2), the recommended backend.

  1. Confirm you're on 64-bit Windows 10 or 11.

  2. Enable WSL2. Docker Desktop can install the WSL2 kernel for you during setup, or you can do it yourself ahead of time — open PowerShell as Administrator and run:

    wsl --install

    Reboot if it asks you to.

  3. Download the installer from docker.com/products/docker-desktop.

  4. Run the installer, keeping the WSL2 backend option selected. Reboot if prompted.

  5. Launch Docker Desktop, accept the terms, and wait for the whale icon in the system tray to stop animating — that means the engine is running.

Verify it works​

Open a new terminal (PowerShell or Windows Terminal) so it picks up the updated PATH, then:

docker --version
docker run hello-world

The first prints a version; the second downloads a tiny image and prints a "Hello from Docker!" message. If both work, Docker is ready.

macOS​

Docker Desktop on macOS ships as two builds. Pick the one that matches your chip:

MacChipBuild to download
M-series (Apple silicon)arm64Apple Chip
Intelamd64Intel Chip

Not sure which you have? Click the Apple menu → About This Mac and read the Chip (or Processor) line.

  1. Download the matching .dmg from docker.com/products/docker-desktop.
  2. Open the .dmg and drag Docker into your Applications folder.
  3. Launch Docker from Applications. Grant the privileged-helper permission when macOS asks (this lets Docker manage networking and containers).
  4. Wait for the whale icon in the menu bar to settle — that means the engine is running.
tip

Prefer Homebrew? brew install --cask docker installs the same Docker Desktop app. You still have to launch it once to grant the helper permission.

Verify it works​

In a new terminal:

docker --version
docker run hello-world

A version string followed by the "Hello from Docker!" message means you're set.

Linux​

On a Linux server, install Docker Engine. The fastest route is Docker's official convenience script.

  1. Download and run the script:

    curl -fsSL https://get.docker.com | sh

    It detects your distribution and installs Docker Engine plus the Compose v2 plugin. (Prefer distro packages? Follow docs.docker.com/engine/install for the apt or dnf instructions.)

  2. Add your user to the docker group so you can run Docker without sudo:

    sudo usermod -aG docker $USER

  3. Log out and back in (or run newgrp docker) so the new group membership takes effect.

  4. Confirm the Compose v2 plugin came along:

    docker compose version

Verify it works​

docker --version
docker run hello-world

If hello-world prints its success message without sudo, the group change worked and Docker is ready.

The docker command needs sudo until you re-login

If docker run hello-world fails with a permission error right after install, you haven't started a fresh login session yet. Log out and back in, then try again.

Verify Docker is ready​

Whatever your OS, two checks confirm a working install. The container test:

docker run hello-world
Hello from Docker!
This message shows that your installation appears to be working correctly.

And the Compose plugin, which OpenWA's Compose paths rely on:

docker compose version
Docker Compose version v2.x.x

If both succeed, you're ready to run OpenWA.

Next: run OpenWA without building​

With Docker installed, you don't have to clone the repo and build the image from source. The existing guides do that with docker compose -f docker-compose.dev.yml up -d, which builds the image and installs Chromium on first run — several minutes. Instead, pull the prebuilt image and start in seconds:

mkdir -p data
docker run -d --name openwa-api -p 2785:2785 -v "$(pwd)/data:/app/data" ghcr.io/rmyndharis/openwa:latest

That's the whole gateway — REST API and bundled dashboard — on port 2785. The single ./data bind mount persists the SQLite database, sessions, media, and your API key. The schema initializes automatically on first boot, so there's nothing else to configure.

Confirm it's up:

curl http://localhost:2785/api/health
{ "status": "ok", "timestamp": "2026-06-27T10:00:00.000Z", "version": "0.7.6" }

On first boot OpenWA generates a random admin API key and writes it to data/.api-key in the bind-mounted directory. Read it from the host:

cat data/.api-key
owa_k1_3f8c0a1b9d4e7f2a6c5b8e0d1a2f3c4b5d6e7f8091a2b3c4d5e6f70812a3b4c5

You can also view and create keys in the dashboard at http://localhost:2785.

Pin a version

:latest always tracks the newest release. For reproducible deploys, pin the exact version instead: ghcr.io/rmyndharis/openwa:0.7.6.

From here:

  • Quick Start — the full walkthrough: grab your key, link a session by scanning a QR code, and send your first message.
  • Installation — Docker Compose and PostgreSQL/Redis/S3 setups for when you outgrow the single-container quick start.