Production Setup: Single Instance

This document shows you how to set up a single instance of the WhatsApp Business API client in production.

To complete your initial setup, check our requirements, and follow these steps:

1. Create a biz directory for the setup scripts
2. Get the WhatsApp Business API Client configuration files
3. Set the WA_API_VERSION environment variable
4. Set the database environment variables
5. Set up the local media volume
6. Start the WhatsApp Business API Client
7. Verify the containers are running
8. Perform a health check
9. Register the WhatsApp Business API Client
10. Perform a Second Health Check

Once you have completely set up your instance, you can choose to upgrade it. To uninstall the client, follow these steps.

Before You Start

You will need:

• Install Docker Desktop and Docker Compose
• A server on which 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.
• A standalone database server running a MySQL or PostgreSQL process. The database server should only be a few milliseconds of latency away from the server hosting the WhatsApp Business API client.

Initial Setup of the WhatsApp Business API Client

Step 1: Create a biz Directory for the Setup Scripts

Run the following code in your preferred location for the WhatsApp Business API client:

mkdir ~/biz; cd ~/biz;

Step 2: Get the WhatsApp Business API Client Configuration Files

Clone the prod-docker-compose.yml and db.env configuration files from the Installation directory of the WhatsApp-Business-API-Setup-Scripts GitHub repository to the ~/biz directory you created in Step 1.

Step 3: Set the WA_API_VERSION Environment Variable

The WA_API_VERSION environmental variable should be set to the current version using:

export WA_API_VERSION=current-whatsapp-version

Step 4: Set the Database Environment Variables

Change the database environment variables in the db.env file under the ~/biz directory to reflect your MySQL/PostgreSQL configuration.

WA_DB_ENGINE=MYSQL | PGSQL
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

Step 5: Set up the Local Media Volume

The local media volume (whatsappMedia:/usr/local/wamedia by default) 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 services section from whatsappMedia to the path of the host directory you're using.

services:
  wacore:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ...          
  waweb:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ... 

Step 6: Start the WhatsApp Business API Client

To start the WhatsApp Business API client with 1 Webapp container and 1 Coreapp container, run:

docker-compose -f prod-docker-compose.yml up -d

The resulting output should look like the following:

Creating biz_wacore_1 ... done
Creating biz_waweb_1  ... done

Step 7: Verify the Containers Are Running

You can check that all containers have an UP state by running:

docker-compose -f prod-docker-compose.yml  ps

The resulting output should look like the following:

     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.

Step 8: Perform a Health Check

You can perform a health check on the WhatsApp Business API client using an API call to the health node.

The resulting output should look like the following:

{
    "health": {
        "gateway_status": "unregistered"
    }
}

The response shows a gateway_status of unregistered as the gateway_status because the WhatsApp Business API client is not yet registered.

Step 9: Register the WhatsApp Business API Client

You can register your WhatsApp Business API client using an API call to the account node.

Step 10: Perform a Second Health Check

Perform another health check on the WhatsApp Business API client using an API call to the health node after completing registration.

The resulting output should look like the following:

{
    "health": {
        "gateway_status": "connected"
    }
}

A gateway_status of connected means the Coreapp container is able to connect to the WhatsApp server for checking contacts and sending messages.

Upgrading the WhatsApp Business API Client

Step 1: Change the WA_API_VERSION Environment Variable to the New Version

The WA_API_VERSION environmental variable should be updated to the new version number using:

export WA_API_VERSION=new-whatsapp-version

Step 2: Restart the Docker Containers

Restart the Docker containers by running:

docker-compose -f prod-docker-compose.yml up -d

For MySQL Database Users Upgrading to v2.23.x and Above

You can now make use of a database upgrade service that will let you upgrade your database while your application is still running to avoid downtime.

Step 1: Download the configuration file

The dbupgrade-compose.yml file has fields indicating the container version.

Example:

services:
  dbupgrade:
    image: docker.whatsapp.biz/coreapp:v${WA_API_VERSION:-2.21.3}

Step 2: Start the container

To upgrade an installation, start the dbupgrade-service container with the WA_API_VERSION environment variable set to the latest version:

WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.yml up -d

Note: If you are using an orchestration that restarts the container upon exit irrespective of the exit code, start the service with the EXIT_ON_SUCCESS environment variable set to FALSE in order to avoid exiting the container when the exit code is 0.

Step 3: Allow the upgrade to finish

If the database upgrade is successful, the container will exit with code 0. You can use the following Docker command to track the status:

docker wait your-database-upgrade-container-name

This will output the exit code of the dbupgrade-service container.

Step 4: Restart the Coreapp and Webapp containers

Restart the Coreapp and Webapp Docker containers with the WA_API_VERSION environment variable set to the latest version:

WA_API_VERSION=new-whatsapp-version docker-compose -f prod-docker-compose.yml up -d

For WhatsApp Business API Client Users Upgrading to Version 2.29.3 and Above

If you are upgrading from v2.29.1, v2.29.2 or encountered problems during upgrade to those versions and had to roll back for stability, we recommend you upgrade to v2.29.3, then run the following command on the Webapp Docker container:

chown -R root your-media-directory/incoming your-media-directory/outgoing your-media-directory/shared

Unless you have changed it, the default media directory is /usr/local/wamedia.

Note:

• Since this command can take a while to complete based on pre-existing media volume size, we recommend this command be initiated as soon as you upgrade during the maintenance window.
• This command only modifies ownership of media volumes in the background (There is no impact/downtime for media operations or latency/performance while it is running).
• This is a one-time only upgrade path to fix backward compatibility issues in v2.29.1 and v2.29.2.

Uninstalling the WhatsApp Business API Client

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

The resulting output should look like the following:

Stopping biz_waweb_1  ... done
Stopping biz_wacore_1 ... done
Removing biz_waweb_1  ... done
Removing biz_wacore_1 ... done

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

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

Troubleshooting

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

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

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

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.