Deploy a WhatsApp Bulk Messaging System with Docker

Standing up a self-hosted WhatsApp bulk messaging system that charges nothing per message is easier than it sounds with Docker: you run a database schema, fill in a single .env file and type docker compose up. This guide walks through every step in order, from requirements to QR pairing, from a production deployment with Dokploy to troubleshooting. The system is QR-based (whatsapp-web.js), not the official Business API — so there is no application, no template approval and no per-conversation fee.

1. Before you start: requirements

You will need the following in place before deploying:

To understand how this architecture works and why hosting it on your own server pays off, see self-hosted WhatsApp messaging system.

2. What Docker Compose brings up

A single docker compose up starts four services. Each is deliberately separated so the rate limit lives in exactly one place — the worker.

The server never sending messages is a key design choice: even 100 requests/second to the panel cannot push WhatsApp traffic past human speed. For more on the WhatsApp Web protocol the worker uses, see what is whatsapp-web.js.

3. Step 1 — Set up the database schema

First create a free Supabase project. Open its SQL Editor, paste the schema file from the repo and run it. This creates the notification_messages and whatsapp_web_sessions tables.

# Clone the repo onto your server
git clone https://github.com/user/whatsapp-oto-message.git
cd whatsapp-oto-message

# Paste the contents of supabase/migrations/001_init.sql
# into Supabase > SQL Editor > New query and click Run

Then, from the Supabase settings, note the Project URL and the service_role key; you will add them to .env in the next step.

4. Step 2 — Fill in the .env file

Copy the example file and generate the secrets strongly. Using openssl for random secrets is far safer than guessable passwords.

cp .env.example .env

# Generate strong secrets
openssl rand -hex 32   # for REDIS_PASSWORD
openssl rand -hex 32   # for WA_CONTROL_SECRET

The core fields to fill in .env:

REDIS_PASSWORD=your_generated_32_byte_value
WA_CONTROL_SECRET=your_generated_32_byte_value
SUPABASE_URL=https://xxxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...
TZ=Europe/Istanbul

5. Step 3 — Start the services

One command builds every image and starts the containers in the background:

docker compose up -d --build

# Check the status of the services
docker compose ps

# Follow the worker logs (the QR and sends show up here)
docker compose logs -f whatsapp-worker

The first build can take a few minutes because of Chromium's dependencies. All four services should read running in docker compose ps. If you want to trigger sends from an external app over an HTTP API, HTTP API integration covers the send endpoint and its authentication.

6. Step 4 — Scan the QR code

Once the containers are up, open the panel in a browser and go to the Connection page. The QR code produced by the worker appears there.

1. On your phone, open WhatsApp > Settings > Linked Devices.
2. Tap Link a Device and scan the QR in the panel.
3. The session is stored via LocalAuth on a persistent volume, so you won't need to rescan even if the container restarts.

Your computer does not need to stay on — the system runs on the server. Your phone only needs to reach the internet roughly every two weeks to keep the session alive.

7. Going to production with Dokploy

docker compose up is fine for development, but in production you want a domain, a TLS certificate and automatic restarts. A self-hosted PaaS panel like Dokploy manages the same compose file and makes this simple:

• Define separate domains for the site and the panel (e.g. dispatch-wa.com and panel.dispatch-wa.com).
• Attach the services to a shared dokploy-network.
• Get automatic HTTPS via Let's Encrypt.
• Define persistent volumes for Redis data and the WhatsApp session so a redeploy never loses the session.

8. Troubleshooting

When you run the system for the first time, test with a small list. The rate ceiling is already safe, but if you want to ramp up gradually on a fresh number, apply a number warm-up approach.

Frequently asked questions