Production Setup: Single Instance

This guide will walk you through how to set up a single-instance WhatsApp Business API Client in production.

This document covers:

Prerequisites

It's recommended you set up a single-instance WhatsApp Business API Client on a developer machine following the Developer Setup: Single Instance guide before following this guide to setup the WhatsApp Business API in production.

If you want to reuse the same phone number in production, please refer to the Migration guide before continuing with the rest of this guide. The content in this guide is based on the assumption of a fresh installation using a new phone number.

  1. Install Docker on your system.
  2. If Docker Compose is not bundled with your Docker installation, install it.
  3. A server to run the WhatsApp Business API Client. For system requirements, refer to What are the server system requirements to run the WhatsApp Business API Client? in the FAQ.
  4. A standalone database server running a MySQL process. The database server should only be a few milliseconds of latency away from the server hosting the WhatsApp Business API Client.

MySQL 5.7xx or higher is required.

Your database password should not contain any of these characters: ?{}&~!()^=

Failing to comply with this will likely cause the setup to fail.

There's also a known compatibility issue with MySQL 8. Please avoid using the latest for now, we're actively working on a fix.

Initial Setup

  1. Create a biz directory to store the setup scripts:
    mkdir ~/biz; cd ~/biz;
  2. Clone the prod-docker-compose.yml and db.env configuration files to ~/biz from the installation directory of the WhatsApp-Business-API-Setup-Scripts Github repo.
  3. Change the values in the db.env file to reflect your MySQL configuration:
    WA_DB_ENGINE=MYSQL
    WA_DB_HOSTNAME=your-database-server
    WA_DB_PORT=your-database-server-port
    WA_DB_USERNAME=your-database-username
    WA_DB_PASSWORD=your-database-password
  4. The whatsappMedia volume defined in prod-docker-compose.yml file is used for storing media files. By default, the volume in mounted to a directory on the Docker machine. Alternatively, you can choose to mount the media volume to a host directory. To change the mount point of the media volume, modify the volume definition inside the service section from whatsappMedia to the path of the host directory.
    services:
      wacore:
        ...
        volumes:
          - /path/on/host/media:/usr/local/wamedia
        ...          
      waweb:
        ...
        volumes:
          - /path/on/host/media:/usr/local/wamedia
        ... 
              
  5. Run the following command to start the WhatsApp Business API Client with 1 Webapp container and 1 Coreapp container:
    docker-compose -f prod-docker-compose.yml up -d
    Example output:
    Creating biz_wacore_1 ... done
    Creating biz_waweb_1  ... done
    
  6. Check that all containers have an UP state by running:
    docker-compose -f prod-docker-compose.yml  ps
    Example output:
         Name                    Command               State                   Ports
    -------------------------------------------------------------------------------------------------
    biz_wacore_1   /opt/whatsapp/bin/wait_on_ ...   Up      6250/tcp, 6251/tcp, 6252/tcp, 6253/tcp
    biz_waweb_1    /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:9090->443/tcp
    
    By default, the Webapp container will be running on port 9090.
  7. You can download and configure our Postman Collection to easily interact with the WhatsApp Business API.
  8. Perform a health check to verify the WhatsApp Business API is running properly. Example response:
    {
        "health": {
            "gateway_status": "unregistered"
        }
    }
    
    Because your WhatsApp Business API Client is not registered right now, you will see unregistered in the health status response.
  9. Follow the Registration documentation to register the WhatsApp Business API cilent.
  10. Perform another health check after registration. A connected status means the Coreapp container is able to connect to the WhatsApp server to check contacts and send messages. Example response:
    {
        "health": {
            "gateway_status": "connected"
        }
    }
    

It's recommended you set up monitoring for your production WhatsApp Business API Client, see the Monitoring and Alerting documentation for more information.

Upgrading

It is highly recommended to backup your current application settings before upgrading. Please follow the Backup and Restore documentation.

The prod-docker-compose.yml file has fields indicating container versions. For example:

services:
  ...
  wacore:
      image: docker.whatsapp.biz/coreapp:v${WA_API_VERSION:-2.21.1}
  ...
  waweb:
      image: docker.whatsapp.biz/web:v${WA_API_VERSION:-2.21.1}

To upgrade an installation:

  1. Change the version numbers in the prod-docker-compose.yml file:
    services:
      ...
      wacore:
          image: docker.whatsapp.biz/coreapp:v${WA_API_VERSION:-2.21.6}
      ...
      waweb:
          image: docker.whatsapp.biz/web:v${WA_API_VERSION:-2.21.6}
    
  2. Restart the Docker containers:
    docker-compose -f prod-docker-compose.yml up -d
    Example output:
    Recreating biz_wacore_1 ... done
    Recreating biz_waweb_1  ... done
    
  3. Alternatively, restart the Docker containers with environment variable WA_API_VERSION set to the new version:
    WA_API_VERSION=2.21.6 docker-compose -f prod-docker-compose.yml up -d

Uninstalling

It is highly recommended to backup your current application settings before uninstallation. Please follow the Backup and Restore documentation.

If you need to reset your development environment by removing all containers, run the following command from the directory containing the prod-docker-compose.yml file:

docker-compose -f prod-docker-compose.yml down
Example output:
Stopping biz_waweb_1  ... done
Stopping biz_wacore_1 ... done
Removing biz_waweb_1  ... done
Removing biz_wacore_1 ... done

In order to get rid of all volumes defined in the prod-docker-compose.yml file in addition to the containers, run down with the -v parameter:

docker-compose -f prod-docker-compose.yml down -v

Troubleshooting

We recommend WADebug for more effective troubleshooting. WADebug is a command line tool to help find any potential issues with WhatsApp Business API setup and to make requesting for help from WhatsApp support more effective.

In cases where WADebug cannot be used or running the tool returns errors, to collect logs from all containers, run the following command:

docker-compose -f prod-docker-compose.yml logs > debug_output.txt

To collect logs of a specific service, append the service name (waweb or wacore) to the docker-compose logs command, e.g.:

docker-compose -f prod-docker-compose.yml logs waweb > debug_output.txt

You can find the logs in the debug_output.txt file in the current directory.