> ## 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.

# Production Best Practices

> Run GOWA safely in production: security, storage, backups, reverse proxy, monitoring and sending hygiene.

## Security

* **Set `APP_BASIC_AUTH`** with a long random password. Without it, anyone who can reach the port controls your WhatsApp account.
* **Change `WHATSAPP_WEBHOOK_SECRET`.** The default is `secret`. Verify `X-Hub-Signature-256` on every webhook.
* **Terminate TLS** at a reverse proxy; GOWA itself speaks plain HTTP.
* **Restrict `/statics`.** QR codes and downloaded media under `/statics/*` are served **without** Basic Auth. Block or protect that path at the proxy if media is sensitive, and prune `statics/media` regularly.
* **Do not expose `/chatwoot/webhook` without `CHATWOOT_WEBHOOK_SECRET`** when Chatwoot is enabled.
* **Set `APP_CORS_ALLOWED_ORIGINS`** if browsers call the API directly; empty allows any origin.
* **Bind privately** (`APP_HOST=127.0.0.1` or a private network) when only local services need access.
* Rate-limit failed logins at the proxy; GOWA has no built-in [rate limiting](https://gowa-docs.mintlify.site/advanced/rate-limiting.md).

## Storage and backups

| Path | Contents | Back up? |
| - | - | - |
| `storages/whatsapp.db` (or `DB_URI`) | WhatsApp sessions and keys | Yes. Losing it means re-pairing every device. |
| `storages/chatstorage.db` | Chats, messages, schedules and other GOWA state | Yes |
| `storages/oauth.db` | MCP OAuth clients and token hashes | If OAuth is used |
| `statics/` | QR codes, downloaded and scheduled media | Optional |

* Use PostgreSQL for `DB_URI` if you want managed backups; chat storage is always SQLite.
* Back up while GOWA is stopped, or use your database's online backup tools.
* Store backups encrypted: the session database is equivalent to a logged-in account.
* **Run one GOWA instance per storage.** Two processes sharing a session cause disconnects and conflicts. GOWA does not support horizontal scaling.

## Docker

```bash theme={null}
docker run -d --name gowa --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v gowa-storages:/app/storages \
  -v gowa-statics:/app/statics \
  -e APP_BASIC_AUTH=admin:a-long-random-password \
  -e WHATSAPP_WEBHOOK=https://example.com/wa-hook \
  -e WHATSAPP_WEBHOOK_SECRET=another-long-random-secret \
  aldinokemal2104/go-whatsapp-web-multidevice:v9.7.0 rest
```

* Pin a version tag rather than `latest`, and read the release notes before upgrading.
* The container runs as a non-root user (UID 20001); make sure mounted volumes are writable.
* The image sets `TZ=UTC`. Schedules use the `timezone` you pass, so this does not affect them.

## Reverse proxy

* Set `APP_TRUSTED_PROXIES` to your proxy's address range so client IPs are read correctly.
* Allow WebSocket upgrades on `/ws`.
* Raise the body limit to at least 100 MB (`client_max_body_size 100m;` in nginx).
* Keep proxy timeouts above GOWA's 45-second request timeout.
* For sub-path deployments use `APP_BASE_PATH`; `/health` remains at the root.

See [Installation](https://gowa-docs.mintlify.site/installation.md#behind-a-reverse-proxy) for an nginx example.

## Monitoring

* **Liveness:** `GET /health` returns `200 OK` when the process and store are up. It does not check WhatsApp.
* **WhatsApp connectivity:** poll `GET /devices/{device_id}/status` and alert when `is_logged_in` is `false`.
* **Events:** subscribe to webhooks and alert on missing traffic for busy numbers.
* **Logs:** collect container stdout; use `APP_DEBUG=true` only while troubleshooting.

GOWA reconnects automatically on startup and checks connections every 5 minutes. A device logged out from the phone must be paired again.

## Webhook receivers

* Respond `2xx` within 10 seconds; process work asynchronously.
* Deduplicate by message `id`: retries can deliver an event more than once.
* After 5 failed attempts the event is dropped. Use `GET /chats` and `GET /chat/{jid}/messages` to catch up after an outage.

## Sending hygiene

* Message people who opted in or wrote first.
* Pace sends with delays and jitter; avoid identical bulk text.
* Stop on `WA_REACHOUT_TIMELOCK`.
* Keep `WHATSAPP_ACCOUNT_VALIDATION=true` so unregistered numbers fail fast.
* WhatsApp allows up to four linked companion devices per account, and unlinks companions after about 14 days if the phone stays offline.


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