Configuration de production : instance unique

Ce document explique comment configurer une instance unique du client de l’API WhatsApp Business en production.

Pour la configuration initiale, consultez nos exigences et suivez ces étapes :

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

• Docker Desktop et Docker Compose installés.
• Un serveur sur lequel exécuter le client de l’API WhatsApp Business. 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.
• Un serveur de base de données autonome exécutant un processus MySQL ou PostgreSQL. Le serveur de base de données ne doit avoir que quelques millisecondes de latence par rapport au serveur qui héberge le client de l’API WhatsApp Business.

Configuration initiale du client de l’API WhatsApp Business

É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-docker-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 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é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 5 : 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:
  wacore:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ...          
  waweb:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ... 

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

Pour démarrer le client de l’API WhatsApp Business avec un conteneur Webapp et un conteneur Coreapp, exécutez :

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

La sortie de cette commande doit se présenter comme suit :

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

Étape 7 : 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 prod-docker-compose.yml  ps

La sortie de cette commande doit se présenter comme suit :

     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

Par défaut, le conteneur Webapp s’exécute sur le port 9090.

Étape 8 : 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.

La sortie de cette commande doit se présenter comme suit :

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

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

Étape 9 : 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 10 : Effectuer un deuxième contrôle de l’état

Effectuez un autre contrôle de l’état du client de l’API WhatsApp Business en envoyant un appel d’API au nœud health après avoir finalisé l’inscription.

La sortie de cette commande doit se présenter comme suit :

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

Un gateway_statusconnected signifie que le conteneur Coreapp peut se connecter au serveur WhatsApp pour vérifier les contacts et envoyer des messages.

Mise à jour du client de l’API WhatsApp Business

É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 prod-docker-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 prod-docker-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

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 prod-docker-compose.yml :

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

La sortie de cette commande doit se présenter comme suit :

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

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

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

Dépannage

Si vous ne pouvez pas utiliser WADebug ou que son exécution renvoie des erreurs, exécutez la commande suivante pour recueillir les journaux de tous les conteneurs :

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

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

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

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