API On-Premises de la plateforme WhatsApp Business

Configuration de développeur : haute disponibilité et Multiconnect

Ce document explique comment configurer un cluster à haute disponibilité sur une machine de développeur·se. Il vous aidera également à activer Multiconnect et indiquera les modifications requises pour un cluster Multiconnect hautement disponible. Pour une configuration en production, suivez les instructions correspondantes de la section Configurations en production.

Avant de commencer ces configurations, vérifiez notre liste de conditions requises.

Pour configurer un cluster à haute disponibilité, suivez les étapes ci-dessous :

  1. Créer un répertoire biz pour les scripts de configuration
  2. Obtenir les fichiers de configuration du client de l’API WhatsApp Business
  3. Définir la variable d’environnement WA_API_VERSION
  4. Démarrer le client de l’API WhatsApp Business en haute disponibilité
  5. Vérifier que les conteneurs s’exécutent
  6. Effectuer un contrôle de l’état
  7. Inscrire le client de l’API WhatsApp Business
  8. Effectuer un second contrôle de l’état

Pour configurer un cluster Multiconnect, suivez les étapes ci-dessous :

  1. Configurer deux partitions
  2. Effectuer un contrôle de l’état
  3. Démarrer un troisième Coreapp pour maintenir la haute disponibilité
  4. Effectuer un second contrôle de l’état

Une fois que votre instance est entièrement configurée, vous pouvez choisir de mettre à jour le client. Pour désinstaller le client, suivez ces étapes.

Avant de commencer

Si vous avez suivi précédemment les instructions Configuration de développeur : instance unique afin de configurer un client de l’API WhatsApp Business sur une machine de développeur·se, veuillez consulter le guide sur la migration avant de poursuivre ce document.

Le contenu de ce guide est basé sur le principe d’une nouvelle installation.

Avant de commencer, vérifiez que vous possédez les éléments suivants :

Install Docker Desktop

To install Docker Desktop on your developer machine:

  1. Navigate to the Docker website.
  2. If you do not have an existing Docker account, create one by clicking on Sign Up.
  3. After you have created your account, you will be directed to the Docker download page.
  4. Download Docker Desktop based on your OS (This should be automatically detected and presented as the default option).

The remaining steps are based on macOS and should be very similar for Linux or Windows 10.

To install Docker using macOS:

  1. Install the package (docker.dmg for macOS).
  2. After extraction, Finder will pop-up and you will be presented with a dialog that instructs you to drag the Docker icon to Applications. Drag Docker icon to the Application folder in Finder.
  3. In Applications launch Docker and then click the Open button.
  4. You may be prompted to enter your password Docker needs priviledged/administrator access.
  5. Docker will present you with a tutorial, you can click Start to launch a tutorial or you can click Skip Tutorial to start using Docker.

Verify Docker Compose is installed

Docker Compose is a plugin that is bundled with Docker Desktop and should have installed automatically. For more information about using or Docker Compose, see Overview of Docker Compose. If for some reason Docker Compose was not installed, you can install it by following the instructions located at Install Docker Compose.

Autres conditions requises

Configurez un compte de test localement dans un environnement de développement. Il assure un développement rapide et permettra de tester les nouvelles versions. Il est également fortement recommandé de lire le guide sur la disponibilité et la mise à l’échelle pour en savoir plus sur la haute disponibilité et Multiconnect.

Configurer un cluster à haute disponibilité

Étape 1 : Créer un répertoire biz pour les scripts de configuration

Exécutez le code suivant à l’emplacement de votre choix pour le client de l’API WhatsApp Business :

mkdir ~/biz; cd ~/biz;

Étape 2 : Obtenir les fichiers de configuration du client de l’API WhatsApp Business

Les fichiers de configuration du client de l’API WhatsApp Business se trouvent dans le dépôt GitHub WhatsApp-Business-API-Setup-Scripts. Vous pouvez configurer votre client d’API WhatsApp Business avec une instance de base de données MySQL ou Postgres.

Étape 3 : Définir la variable d’environnement WA_API_VERSION

La variable d’environnement WA_API_VERSION doit être définie sur la version actuelle avec la commande :

export WA_API_VERSION=current-whatsapp-version

Étape 4 : Démarrer le client de l’API WhatsApp Business en haute disponibilité

Pour démarrer un cluster à haute disponibilité avec un conteneur de base de données, un conteneur Webapp, deux conteneurs Maître et deux conteneurs Coreapp en arrière-plan similaires au diagramme illustré dans l’introduction à la haute disponibilité, exécutez la commande suivante :

docker-compose -f multiconnect-compose.yml up -d db waweb master1 master2 wacore1 wacore2

Le résultat de cette commande doit se présenter comme suit :

Creating network "biz_default" with the default driver
Creating volume "biz_mysqlData" with local driver
Creating volume "biz_whatsappMedia" with local driver
Creating biz_db_1 ... done
Creating biz_waweb_1 ... done
Creating biz_master1_1 ... done
Creating biz_master2_1 ... done
Creating biz_wacore2_1 ... done
Creating biz_wacore1_1 ... done

Étape 5 : Vérifier que les conteneurs s’exécutent

Pour vérifier que l’état de tous les conteneurs est UP, exécutez :

docker-compose -f multiconnect-compose.yml ps

Le résultat de cette commande doit se présenter comme suit :

      Name                    Command               State                                                 Ports
--------------------------------------------------------------------------------------------------------------------------------------------------------------
biz_db_1        docker-entrypoint.sh mysqld      Up      0.0.0.0:33060->3306/tcp, 33060/tcp
biz_master1_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32931->6250/tcp, 0.0.0.0:32930->6251/tcp, 0.0.0.0:32928->6252/tcp, 0.0.0.0:32926->6253/tcp
biz_master2_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32929->6250/tcp, 0.0.0.0:32927->6251/tcp, 0.0.0.0:32925->6252/tcp, 0.0.0.0:32924->6253/tcp
biz_wacore1_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32937->6250/tcp, 0.0.0.0:32935->6251/tcp, 0.0.0.0:32933->6252/tcp, 0.0.0.0:32932->6253/tcp
biz_wacore2_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32939->6250/tcp, 0.0.0.0:32938->6251/tcp, 0.0.0.0:32936->6252/tcp, 0.0.0.0:32934->6253/tcp
biz_waweb_1     /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:9090->443/tcp

Par défaut, le conteneur Webapp fonctionnera sur le port 9090 et le conteneur de base de données sur le port 33060.

Étape 6 : Effectuer un contrôle de l’état

Vous pouvez télécharger et configurer notre collection Postman pour interagir avec l’API WhatsApp Business si vous ne souhaitez pas utiliser la ligne de commande.

Vous pouvez contrôler l’état du client de l’API WhatsApp Business en envoyant un appel d’API au nœud health.

Le résultat de cette commande doit se présenter comme suit :

{
    "health": {
      "master1:b28d835cd579": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      },
      "master2:7fe542d305b4": {
          "gateway_status": "unregistered",
          "role": "primary_master"
      },
      "wacore1:35a5fabfc79d": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      },
      "wacore2:05e1a6d70665": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      }
  }
}

La réponse affiche un gateway_statusunregistered comme gateway_status pour le conteneur Maître principal, car le client de l’API WhatsApp Business n’est pas encore inscrit.

Étape 7 : Inscrire le client de l’API WhatsApp Business

Vous pouvez inscrire votre client de l’API WhatsApp Business en envoyant un appel d’API au nœud account.

Étape 8 : Effectuer un second contrôle de l’état

Effectuez un autre contrôle de l’état du client de l’API WhatsApp Business en utilisant un appel d’API sur le nœud health après avoir finalisé l’inscription et assurez-vous que l’un des conteneurs Coreapp a un gateway_statusconnected.

Le résultat de cette commande doit se présenter comme suit :

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "disconnected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}

Remarque : en mode haute disponibilité, un seul Coreapp (wacore1 dans cet exemple) sera connecté au serveur Whatsapp, tous les autres nœuds, y compris le Maître principal, auront un gateway_statusdisconnected. Si wacore1 tombe en panne, wacore2 le remplacera et se connectera au serveur WhatsApp pour maintenir la haute disponibilité.

Vous avez désormais configuré le client de l’API WhatsApp Business en mode haute disponibilité. Dans ce mode, seul un Coreapp peut se connecter au serveur WhatsApp pour envoyer des messages à tout moment. Si vous souhaitez que plusieurs Coreapp envoient des messages simultanément pour augmenter le débit des messages, suivez les étapes de la section Configurer un cluster Multiconnect hautement disponible ci-dessous.

Configurer un cluster Multiconnect hautement disponible

Étape 1 : Configurer deux partitions

Utilisez le point de terminaison « shards » pour configurer deux partitions. La réponse HTTP devrait renvoyer l’état 201 Created.

Étape 2 : Effectuer un contrôle de l’état

Vous pouvez contrôler l’état du client de l’API WhatsApp Business en envoyant un appel d’API au nœud health.

Le résultat de cette commande doit se présenter comme suit :

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "connected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "connected",
            "role": "coreapp"
        }
    }
}

Remarque : en mode Multiconnect avec deux partitions, deux Coreapp (wacore1 et wacore2 dans cet exemple) seront connectés au serveur WhatsApp, et le Maître principal (master2 dans cet exemple) se connectera également au serveur WhatsApp.

Étape 3 : Démarrer un troisième Coreapp pour maintenir la haute disponibilité

Dans cet exemple, nous avons pour l’instant deux conteneurs Coreapp et les charges des messages sont réparties entre eux. Cependant, si l’un des conteneurs Coreapp tombe en panne, la moitié des messages ne sera pas envoyée. Afin de maintenir la haute disponibilité dans cette nouvelle configuration Multiconnect, vous pouvez démarrer un troisième Coreapp pour tolérer l’échec d’un Coreapp, comme illustré dans le diagramme dans l’introduction à Multiconnect.

Pour démarrer le troisième conteneur Coreapp, exécutez la commande suivante :

docker-compose -f multiconnect-compose.yml up -d wacore3

Le résultat de cette commande doit se présenter comme suit :

biz_db_1 is up-to-date
biz_waweb_1 is up-to-date
biz_master1_1 is up-to-date
Creating biz_wacore3_1 ... done

Étape 4 : Effectuer un second contrôle de l’état

Effectuez un autre contrôle de l’état pour vérifier que tous les nœuds fonctionnent correctement en utilisant un appel d’API sur le nœud health.

Le résultat de cette commande doit se présenter comme suit :

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "connected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore3:23b50199bec2": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}

Le nouveau conteneur Coreapp (wacore3 dans cet exemple) agit maintenant comme conteneur de secours, mais il n’est actuellement pas connecté au serveur WhatsApp. Si wacore1 ou wacore2 cesse de fonctionner, wacore3 se connectera au serveur WhatsApp pour maintenir un nombre total de deux partitions.

Mise à jour du client de l’API WhatsApp Business

Il y aura un temps d’arrêt pendant la mise à jour.

Il est fortement recommandé de sauvegarder vos paramètres d’application avant de lancer une mise à jour afin de vous assurer de pouvoir reprendre votre activité rapidement. Veuillez consulter la documentation sur la sauvegarde et la restauration.

Il est toujours recommandé d’effectuer les mises à jour pendant les heures creuses.

Étape 1 : Modifier la variable d’environnement WA_API_VERSION sur la nouvelle version

La variable d’environnement WA_API_VERSION doit toujours être mise à jour de manière à indiquer le numéro de la nouvelle version avec la commande :

export WA_API_VERSION=new-whatsapp-version

Étape 2 : Redémarrer les conteneurs Docker

Redémarrez les conteneurs Docker en exécutant :

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

Pour les utilisateur·ices de bases de données MySQL passant à v2.23.x ou une version ultérieure

Vous pouvez maintenant utiliser un service de mise à jour qui vous permettra de mettre à jour votre base de données pendant l’exécution de votre application, pour éviter les temps d’arrêt.

Étape 1 : Télécharger le fichier de configuration

Le fichier dbupgrade-compose.yml contient des champs indiquant la version du conteneur.

Exemple :

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

Étape 2 : Démarrer le conteneur

Pour mettre à jour une installation, démarrez le conteneur dbupgrade-service avec la variable d’environnement WA_API_VERSION définie sur la dernière version :

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

Remarque : si vous utilisez une orchestration qui redémarre le conteneur à la sortie indépendamment du code de sortie, démarrez le service avec la variable d’environnement EXIT_ON_SUCCESS définie sur FALSE pour éviter de quitter le conteneur lorsque le code de sortie est 0.

Étape 3 : Laisser la mise à jour se terminer

Si la mise à jour de la base de données est réussie, le code de sortie du conteneur sera 0. Vous pouvez utiliser la commande Docker suivante pour suivre l’état :

docker wait your-database-upgrade-container-name

Le code de sortie du conteneur dbupgrade-service sera alors indiqué dans la sortie.

Étape 4 : Redémarrer les conteneurs Coreapp et Webapp

Redémarrez les conteneurs Docker Coreapp et Webapp avec la variable d’environnement WA_API_VERSION définie sur la dernière version :

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

Désinstallation du client de l’API WhatsApp Business

Il est fortement recommandé de sauvegarder vos paramètres d’application avant de lancer une procédure de désinstallation. Veuillez consulter la documentation sur la sauvegarde et la restauration.

Pour réinitialiser votre environnement de développement en supprimant tous les conteneurs, exécutez la commande suivante depuis le répertoire contenant le fichier multiconnect-compose.yml :

docker-compose -f multiconnect-compose.yml down

Afin de supprimer également tous les volumes définis dans le fichier multiconnect-compose.yml, exécutez down avec le paramètre -v :

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

Résolution des problèmes

Pour recueillir les journaux de tous les conteneurs, exécutez la commande suivante :

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

Pour recueillir les journaux d’un service spécifique, ajoutez le nom du service (p. ex. waweb, master1, wacore1) à la commande docker-compose logs :

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

Vous trouverez les journaux dans le fichier debug_output.txt enregistré dans le répertoire actuel.

Ce logiciel utilise le code de FFmpeg sous licence du LGPLv2.1 et sa source peut être téléchargée ici.