Configuration de production : haute disponibilité et Multiconnect

Ce document explique comment configurer un cluster à haute disponibilité en production. Il vous aidera également à activer Multiconnect et indiquera les modifications requises pour un cluster Multiconnect hautement disponible.

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

Pour configurer un cluster à haute disponibilité :

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 les variables d’environnement de la base de données
4. Configurer le volume de contenu multimédia local
5. Démarrer le client de l’API WhatsApp Business
6. Vérifier que les conteneurs s’exécutent
7. Effectuer un contrôle de l’état
8. Inscrire le client de l’API WhatsApp Business
9. Effectuer un second contrôle de l’état

Pour configurer un cluster Multiconnect à haute disponibilité :

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

Vous aurez besoin des éléments suivants :

• Plusieurs serveurs de calcul pour exécuter les différents composants du client de l’API WhatsApp Business (à savoir Webapp, Maître et Coreapp)

  • Pour connaître la configuration système requise, consultez la section Quelle est la configuration système requise pour exécuter le client de l’API WhatsApp Business ? des questions-réponses.
  • Pour une configuration de production à haute disponibilité, nous recommandons au moins une machine pour le conteneur Webapp, deux machines pour les conteneurs Coreapp et deux machines pour les conteneurs Maîtres. La charge sur les Maîtres est légère et vous pouvez colocaliser les conteneurs Maîtres et Coreapp sur le même hôte.
• Docker Desktop et Docker Compose installés
• Un serveur de base de données autonome exécutant un processus MySQL ou PostgreSQL

  • Le serveur de base de données ne doit pas s’exécuter sur l’un des autres serveurs de calcul hébergeant le client de l’API WhatsApp Business et la latence avec les autres serveurs de calcul ne doit pas être supérieure à quelques millisecondes.

• Un système de fichiers partagés (par exemple NFS) monté sur un répertoire local sur tous les hôtes Webapp, Maître et Coreapp, si vous souhaitez pouvoir envoyer et recevoir des messages multimédias

  • Assurez-vous de définir le mode de fichier sur 755 pour le chemin de montage et tous ses sous-répertoires.

mkdir your-local-media-volume-path
mount -t nfs nfs_server_IP_addr:/shared_directory /your-local-media-volume-path

Configurer un cluster hautement disponible

É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

Clonez les fichiers de configuration prod-multiconnect-compose.yml et db.env situés dans le répertoire Installation du dépôt GitHub WhatsApp-Business-API-Setup-Scripts dans le répertoire ~/biz que vous avez créé à l’étape 1.

Étape 3 : Définir les variables d’environnement de la base de données

Modifiez les variables d’environnement de la base de données dans le fichier db.env du répertoire ~/biz de sorte qu’elles correspondent à votre configuration MySQL/PostgreSQL.

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

Étape 4 : Configurer le volume de contenu multimédia local

Le volume de contenu multimédia local (whatsappMedia:/usr/local/wamedia, par défaut) défini dans le fichier prod-docker-compose.yml sert à stocker les fichiers multimédias. Par défaut, le volume est monté dans un répertoire sur la machine Docker. Vous pouvez toutefois choisir de le monter dans un répertoire hôte. Pour modifier le point de montage du volume de contenu multimédia, indiquez le chemin d’accès au répertoire hôte que vous utilisez dans la définition du volume, à la section services de whatsappMedia.

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

Étape 5 : Démarrer le client de l’API WhatsApp Business

Pour démarrer le client de l’API WhatsApp Business avec un conteneur Webapp, deux conteneurs Maîtres et deux conteneurs Coreapp comme illustré sur le diagramme Introduction à la haute disponibilité, utilisez les commandes suivantes en y apportant les modifications nécessaires pour votre environnement (c’est-à-dire noms d’hôtes, noms d’utilisateur·ices hôtes et chemins d’accès locaux) :

# copy configuration scripts to each Webapp host, ssh to each Webapp host, execute scripts to install Webapp on the host
for host in your-webapp-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd waweb
done 
# copy configuration scripts to each Master host, ssh to each Master host, execute scripts to install Master on the host
for host in your-master1-hostname your-master2-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd master
done
# copy configuration scripts to each Coreapp host, ssh to each Coreapp host, execute scripts to install Coreapp on the host
for host in your-coreapp1-hostname your-coreapp2-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd wacore
done

En résumé, les commandes ci-dessus effectuent les opérations suivantes :

• Copier les fichiers de configuration prod-multiconnect-compose.yml et db.env sur tous les hôtes Webapp (your-webapp-hostname dans cet exemple) et lancer le service waweb sur ces hôtes
• Copier les fichiers de configuration prod-multiconnect-compose.yml et db.env sur tous les hôtes Maîtres (your-master1-hostname et your-master2-hostname dans cet exemple) et démarrer le service Maître sur ces hôtes
• Copier les fichiers de configuration prod-multiconnect-compose.yml et db.env sur tous les hôtes Coreapp (your-coreapp1-hostname et your-coreapp2-hostname dans cet exemple) et démarrer le service wacore sur ces hôtes

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

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

EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f prod-multiconnect-compose.yml ps

Étape 7 : Contrôler 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": {
        "your-master1-hostname:85cdd51506fd": {
            "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
            ]
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "unregistered",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
            ]
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
            ]
        }
    }
}
200

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

Étape 8 : 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 9 : 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": {
        "your-master1-hostname:85cdd51506fd": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "disconnected",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}
200

Remarque : en mode haute disponibilité, un seul Coreapp (your-coreapp1-hostname:753efb1cf72c dans cet exemple) sera connecté au serveur WhatsApp, tous les autres nœuds, y compris le Maître principal, auront un gateway_statusdisconnected. Si your-coreapp1-hostname:753efb1cf72c connaît une défaillance, your-coreapp2-hostname:75d7355eaaaa le remplacera et se connectera au serveur WhatsApp afin de 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 afin de vérifier que tous les nœuds s’exécutent correctement.

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

{
    "health": {
        "your-master1-hostname:85cdd51506fd": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "connected",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "gateway_status": "connected",
            "role": "coreapp"
        }
    }
}      
200    

Remarque : en mode Multiconnect avec deux partitions, deux Coreapps (your-coreapp1-hostname:753efb1cf72c et your-coreapp2-hostname:75d7355eaaaa dans cet exemple) seront connectés au serveur WhatsApp, et le Maître principal (your-master2-hostname:8dd3f5bea27d 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 sur un nouvel hôte Coreapp (

dans cet exemple) afin de tolérer la défaillance d’un Coreapp, de manière similaire au diagramme figurant dans l’introduction à Multiconnect.

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

# copy configuration scripts to the 3rd Coreapp host, ssh to the Coreapp host, execute scripts to install Coreapp on the host
for host in your-coreapp3-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd wacore
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": {
        "your-master1-hostname:85cdd51506fd": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "disconnected",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp3-hostname:23b50199bec2": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}      
200 

Le nouveau conteneur Coreapp (your-coreapp3-hostname:23b50199bec2 dans cet exemple) agit maintenant comme conteneur de secours, mais il n’est actuellement pas connecté au serveur WhatsApp. Si l’un des deux autres conteneurs Coreapp connectés cesse de fonctionner, le troisième se connectera au serveur WhatsApp afin de maintenir un nombre total de deux partitions.

Règles et recommandations

Nombre de Webapps

Nous vous recommandons l’utilisation d’au moins deux Webapps pour une charge de 100 à 150 messages/sec. Si vous voulez profiter de la haute disponibilité pour Webapp, vous pouvez exécuter les conteneurs Webapp sur plus de deux hôtes et les héberger derrière un répartiteur de charge tel que HAProxy, Nginx ou ELB. Au lieu d'accéder aux points de terminaison de client de l'API WhatsApp Business via https://your-webapp-hostname:your-webapp-port/, vous devriez utiliser https://your-load-balancer-name:your-load-balancer-port/.

Nombre de Maîtres

Nous vous recommandons de disposer de trois Maîtres s’exécutant sur des hôtes différents. Il est inutile de disposer de plus de trois Maîtres en production, peu importe le nombre de partitions. La charge sur les Maîtres est légère et vous pouvez les colocaliser avec des conteneurs Coreapp.

Nombre de Coreapps

Nous vous recommandons de disposer de shard_number + X Coreapps s’exécutant sur des hôtes différents afin de pouvoir tolérer X défaillances d’hôtes.

Mise à jour du client de l’API WhatsApp Business

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 : Exécutez les commandes suivantes en y apportant les changements nécessaires pour votre environnement (c’est-à-dire noms d'hôtes, noms d'utilisateur·ices hôtes et chemins d’accès locaux) :

# ssh to each Webapp host, execute scripts with new WA_API_VERSION to upgrade Webapp on the host
for host in your-webapp-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.x docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd waweb
done
# ssh to each Master host, execute scripts with new WA_API_VERSION to upgrade Master on the host
for host in your-master1-hostname your-master2-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.x docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd master
done
# ssh to each Coreapp host, execute scripts with new WA_API_VERSION to upgrade Coreapp on the host
for host in your-coreapp1-hostname your-coreapp2-hostname your-coreapp3-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.x docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd wacore
done

Pour les utilisateur·ices de bases de données MySQL passant à la version 2.23.x et supé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 :

EXTERNAL_HOSTNAME=$host_to_upgradedb 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 :

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

Pour les utilisateur·ices du client de l’API WhatsApp Business passant à 2.29.3 ou une version ultérieure

Si vous effectuez une mise à jour de v2.29.1 à v2.29.2ou rencontrez des problèmes durant la mise à jour de ces versions et que vous devez revenir à l’ancienne version pour des raisons de stabilité, nous vous recommandons d’effectuer la mise à jour vers v2.29.3, puis d’exécuter la commande suivant sur le conteneur Webapp Docker :

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

Si vous ne l’avez pas modifié, le répertoire de contenu multimédia par défaut est /usr/local/wamedia.

Remarque :

• Sachant que l’exécution de cette commande peut prendre du temps en fonction de la taille du volume de contenu multimédia existant, nous vous recommandons de la lancer dès que vous procédez à la mise à jour durant la fenêtre de maintenance.
• Cette commande ne modifie que la propriété des volumes de contenu multimédia en arrière-plan (son exécution ne provoque pas de temps d’arrêt ni de perturbation des opérations à contenu multimédia et n’a pas d’impact sur la latence ou les performances).
• Il s’agit d’une méthode ponctuelle de mise à jour permettant de résoudre les problèmes de rétrocompatibilité avec v2.29.1 et v2.29.2.

Désinstallation du client de l’API WhatsApp Business

Si vous devez réinitialiser votre environnement de développement en supprimant tous les conteneurs, utilisez les commandes suivantes en y apportant les changements nécessaires pour votre environnement (c’est-à-dire noms d'hôtes, noms d'utilisateur·ices hôtes et chemins d’accès locaux) :

# ssh to each Webapp host, execute scripts to uninstall Webapp on the host
for host in your-webapp-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-docker-compose.yml down"
    ssh username@$host $cmd waweb
done
# ssh to each Master host, execute scripts to uninstall Master on the host
for host in your-master1-hostname your-master2-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-docker-compose.yml down"
    ssh username@$host $cmd master
done
# ssh to each Coreapp host, execute scripts to uninstall Coreapp on the host
for host in your-coreapp1-hostname your-coreapp2-hostname your-coreapp3-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-docker-compose.yml down"
    ssh username@$host $cmd wacore
done

Dépannage

Exécutez la commande suivante pour collecter les journaux de tous les conteneurs d’un hôte :

EXTERNAL_HOSTNAME=$host_to_collect_logs docker-compose -f /local/path/prod-multiconnect-compose.yml logs > debug_output.txt

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

EXTERNAL_HOSTNAME=$host_to_collect_logs docker-compose -f /local/path/prod-multiconnect-compose.yml logs waweb > debug_output.txt

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