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:

Mac	Chip	Build to download
M-series (Apple silicon)	arm64	Apple Chip
Intel	amd64	Intel 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

With Docker working, you don't have to clone the repo or build anything — a single docker run of the prebuilt image starts the whole gateway, REST API and bundled dashboard, on port 2785. Quick Start gives that command and then walks the rest: reading your API key, linking a WhatsApp account by scanning a QR code, and sending your first message.

From here:

• Quick Start — the five-minute path from docker run to a delivered message.
• Installation — the Compose files, pinning an image version, and PostgreSQL/Redis/S3 setups for when you outgrow the single container.