> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install GOWA with Docker, Docker Compose, a release binary or from source, and run it behind a reverse proxy.

![GOWA Deployment And Access Overview](https://mintcdn.com/gowa-docs/xwa06XWUO2vnG9_f/images/GOWA-Deployment-and-Access-Overview.png?fit=max\&auto=format\&n=xwa06XWUO2vnG9_f\&q=85\&s=dc847e074e7578d3cfb8c83f1d756040)

GOWA ships as one binary. The REST API, webhooks, dashboard and MCP endpoint all start with `whatsapp rest`.

## Requirements

| Item | Needed for |
| - | - |
| FFmpeg | Media conversion (video, voice notes). Included in the Docker image. |
| libwebp tools (`cwebp`, `dwebp`, `webpmux`) | Stickers, including animated WebP. Included in the Docker image. |
| Go 1.26+ | Building from source only. |

Supported platforms: Linux (amd64, arm64, armv7, 386), macOS (Intel, Apple Silicon), Windows (amd64, 386; WSL recommended).

## Docker

Images are published to Docker Hub and GHCR:

* `aldinokemal2104/go-whatsapp-web-multidevice`
* `ghcr.io/aldinokemal/go-whatsapp-web-multidevice`

```bash theme={null}
docker volume create gowa_storages
docker volume create gowa_statics

docker run -d --name gowa --restart always \
  -p 3000:3000 \
  -v gowa_storages:/app/storages \
  -v gowa_statics:/app/statics \
  -e APP_BASIC_AUTH=admin:changeme \
  aldinokemal2104/go-whatsapp-web-multidevice:latest
```

* `/app/storages` holds the SQLite databases (sessions, chat history, schedules, OAuth). Losing it unpairs every device.
* `/app/statics` holds QR images, uploads and downloaded media.
* The default command is `rest`. Pass flags after it, for example `... go-whatsapp-web-multidevice rest --autoreply="Away"`.
* The entrypoint fixes volume ownership and drops privileges to `gowauser` (UID 20001, GID 20000).
* Container time is UTC (`TZ=UTC`). Override `TZ` if you need local log timestamps.

### Docker Compose

```yaml docker-compose.yml theme={null}
services:
  gowa:
    image: aldinokemal2104/go-whatsapp-web-multidevice:latest
    container_name: gowa
    restart: always
    ports:
      - "3000:3000"
    environment:
      APP_BASIC_AUTH: admin:changeme
      WHATSAPP_WEBHOOK: https://example.com/wa-hook
      WHATSAPP_WEBHOOK_SECRET: ${WHATSAPP_WEBHOOK_SECRET}
    volumes:
      - gowa_storages:/app/storages
      - gowa_statics:/app/statics

volumes:
  gowa_storages:
  gowa_statics:
```

Generate a stable webhook key with `openssl rand -hex 32` and set `WHATSAPP_WEBHOOK_SECRET` in your shell or Compose `.env` before starting this example.

The repository's own `docker-compose.yml` builds the image from `docker/golang.Dockerfile` and reads `src/.env`. Use it when you want to build locally: `cp src/.env.example src/.env && docker compose up -d --build`.

## Release binary

Download an archive from [GitHub Releases](https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases/latest). Archives are named `whatsapp_<version>_<os>_<arch>.zip`, for example:

```bash theme={null}
curl -fLO https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases/download/v9.9.0/whatsapp_9.9.0_linux_amd64.zip
unzip whatsapp_9.9.0_linux_amd64.zip
chmod +x whatsapp
./whatsapp rest --basic-auth=admin:replace-with-a-strong-password
```

Install the media tools on the host:

```bash theme={null}
# Debian/Ubuntu
sudo apt install ffmpeg webp
# macOS
brew install ffmpeg webp
```

Verify the download against `checksums.txt` from the same release. `./whatsapp version` prints the version; `./whatsapp --help` lists every flag.

## From source

```bash theme={null}
git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.git
cd go-whatsapp-web-multidevice/src
cp .env.example .env    # optional
go build -o whatsapp
./whatsapp rest --basic-auth=admin:replace-with-a-strong-password
```

On macOS also `export CGO_CFLAGS_ALLOW="-Xpreprocessor"` before building.

### ARM without a C toolchain

The `purego` build tag selects a pure-Go SQLite driver, so you can cross-compile with CGO disabled:

```bash theme={null}
# Raspberry Pi 2/3/4 (ARMv7)
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -tags purego -o whatsapp-armv7
# Raspberry Pi Zero/1 (ARMv6)
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=6 go build -tags purego -o whatsapp-armv6
```

## Storage

By default everything is SQLite under `storages/`:

| Data | Default | Setting |
| - | - | - |
| WhatsApp sessions and keys | `file:storages/whatsapp.db` | `DB_URI` |
| Session key cache (optional, separate DB) | uses `DB_URI` | `DB_KEYS_URI` |
| Chat history, device registry, schedules | `file:storages/chatstorage.db` | not configurable |
| MCP OAuth clients and tokens | `file:storages/oauth.db` | `MCP_OAUTH_DB_URI` |

`DB_URI` also accepts PostgreSQL, for example `postgres://user:pass@host:5432/gowa?sslmode=verify-full`. Remote PostgreSQL session stores default to certificate verification when no effective TLS mode is set. Explicit URI, environment, or PostgreSQL service TLS settings still apply. See [storage configuration](https://gowa-docs.mintlify.site/configuration.md#storage).

GOWA creates SQLite files with owner-only `0600` permissions and new parent directories with `0700`. Existing directories keep their permissions. Back up `storages/` (or PostgreSQL plus `storages/`) to keep paired devices across rebuilds. Treat these backups as credentials.

## Behind a reverse proxy

Serve GOWA under a subpath with `APP_BASE_PATH`, and trust the proxy's forwarded headers with `APP_TRUSTED_PROXIES`:

```bash theme={null}
./whatsapp rest --basic-auth=admin:replace-with-a-strong-password \
  --base-path=/gowa --trusted-proxies=10.0.0.0/8
```

```nginx theme={null}
location /gowa/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;     # WebSocket at /gowa/ws
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    client_max_body_size 100m;                  # largest upload GOWA accepts
}
```

`/health` stays at the root (`/health`, not `/gowa/health`) so probes work regardless of base path.

The browser origin guard needs the public host. Preserve `Host` as above, or send `X-Forwarded-Host` from a trusted proxy. A separately hosted dashboard needs its exact origin in `APP_TRUSTED_ORIGINS` or `APP_CORS_ALLOWED_ORIGINS`. A wildcard does not authorize mutations or WebSockets. Serve the dashboard over HTTP or HTTPS, because `file://` pages have an untrusted `null` origin.

The default listener refuses to start without complete Basic Auth credentials. Only enable `APP_ALLOW_UNAUTHENTICATED=true` when the proxy authenticates callers and clients cannot bypass it. For local development without authentication, bind `APP_HOST=127.0.0.1`.

## Verify

```bash theme={null}
curl http://localhost:3000/health                      # OK, no auth needed
curl -u admin:changeme http://localhost:3000/app/info  # server info, no device needed
curl -u admin:changeme http://localhost:3000/devices   # registered devices
```

`/health` returns `OK` once storage is initialized. It does not report whether any WhatsApp account is connected; use `GET /devices/{device_id}/status` for that.

## Upgrading

Back up `storages/`, pull the new image or binary, and restart. Read the [release notes](https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases) for breaking changes first. Notable ones: v6 made the `rest` subcommand mandatory, v7 moved binaries to GoReleaser archives, v8 added multi-device (device-scoped calls need `X-Device-Id` once more than one device exists), and the standalone `whatsapp mcp` mode (`:8080/sse`) was replaced by the `/mcp` endpoint on the REST server.


## Related topics

- [Quickstart](https://gowa-docs.mintlify.site/quickstart.md)
- [Production Best Practices](https://gowa-docs.mintlify.site/advanced/best-practices.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.