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.

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

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