WhatsApp Business Platform On-Premises API

Entwickler-Setup: Hochverfügbarkeit und Multiconnect

In diesem Dokument wird gezeigt, wie du ein Hochverfügbarkeits-Cluster auf einem Entwicklercomputer einrichtest. Außerdem erfährst du, wie du zusätzlich Multiconnect aktivierst und welche Änderungen für ein Hochverfügbarkeits-Multiconnect-Cluster erforderlich sind. Befolge für ein Produktions-Setup die entsprechenden Anweisungen unter Produktions-Setups.

Sieh dir unsere Liste der Anforderungen an, bevor du eines dieser Setups beginnst.

So richtest du ein Hochverfügbarkeits-Cluster ein:

  1. Ein biz-Verzeichnis für die Setup-Skripts erstellen
  2. Die Konfigurationsdateien für den WhatsApp Business API-Client abrufen
  3. Die Umgebungsvariable WA_API_VERSION festlegen
  4. Den WhatsApp Business API-Client mit Hochverfügbarkeit starten
  5. Bestätigen, dass die Container ausgeführt werden
  6. Eine Systemdiagnose durchführen
  7. Den WhatsApp Business API-Client registrieren
  8. Eine zweite Systemdiagnose durchführen

So richtest du ein Multiconnect-Cluster ein:

  1. Zwei Shards einrichten
  2. Eine Systemdiagnose durchführen
  3. Eine dritte Coreapp starten, um Hochverfügbarkeit aufrechtzuerhalten
  4. Eine zweite Systemdiagnose durchführen

Nachdem das Setup deiner Instanz vollständig abgeschlossen ist, kannst du die Instanz upgraden. Mit diesen Schritten kannst du den Client deinstallieren.

Bevor du beginnst

Wenn du die Anweisungen unter Entwickler-Setup: Einzelinstanz zur Einrichtung eines WhatsApp Business API-Clients auf einem Entwicklercomputer befolgt hast, führe die im Migrationsleitfaden aufgeführten Schritte durch, bevor du mit den Schritten in diesem Dokument fortfährst.

Der Inhalt dieses Leitfadens basiert auf der Annahme einer Neuinstallation.

Bevor du beginnst, musst du die folgenden Aufgaben ausführen:

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.

Weitere Voraussetzungen

Vergewissere dich, dass du ein lokales Testkonto in einer Entwicklungsumgebung eingerichtet hast. Das ermöglicht eine schnelle Entwicklung und das Testen neuer Versionen. Außerdem wird dringend empfohlen, den Leitfaden zu Verfügbarkeit und Skalierung zu lesen, um mehr über Hochverfügbarkeit und Multiconnect zu erfahren.

Einrichten eines Hochverfügbarkeits-Clusters

Schritt 1: Ein biz-Verzeichnis für die Setup-Skripts erstellen

Führe den folgenden Code an deinem bevorzugten Speicherort für den WhatsApp Business API-Client aus:

mkdir ~/biz; cd ~/biz;

Schritt 2: Die Konfigurationsdateien für den WhatsApp Business API-Client abrufen

Die Konfigurationsdateien für den WhatsApp Business API-Client befinden sich im GitHub-Repository „WhatsApp-Business-API-Setup-Scripts“. Du kannst deinen WhatsApp Business API-Client mit einer MySQL- oder Postgres-Datenbankinstanz einrichten.

Schritt 3: Die WA_API_VERSION-Umgebungsvariable festlegen

Die WA_API_VERSION-Umgebungsvariable sollte auf die aktuelle Version festgelegt werden. Verwende hierfür:

export WA_API_VERSION=current-whatsapp-version

Schritt 4: Den WhatsApp Business API-Client mit Hochverfügbarkeit starten

Führe den folgenden Befehl aus, um ein Hochverfügbarkeits-Cluster mit einem Datenbankcontainer, einem Webapp-Container, zwei Master-Containern und 2 Coreapp-Containern im Hintergrund zu starten (ähnlich wie im Diagramm zur Einführung von Hochverfügbarkeit):

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

Die Ausgabe sollte in etwa wie folgt aussehen:

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

Schritt 5: Bestätigen, ob Container ausgeführt werden

Du kannst prüfen, ob alle Container den Status UP aufweisen. Führe hierzu Folgendes aus:

docker-compose -f multiconnect-compose.yml ps

Die Ausgabe sollte in etwa wie folgt aussehen:

      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

Standardmäßig wird der Webapp-Container auf Port 9090 und der Datenbankcontainer auf Port 33060 ausgeführt.

Schritt 6: Eine Systemdiagnose durchführen

Du kannst unsere Postman-Sammlung herunterladen und konfigurieren, um mit der WhatsApp Business API zu interagieren, wenn du die Befehlszeile nicht verwenden möchtest.

Du kannst auf dem WhatsApp Business API-Client eine Systemdiagnose durchführen. Führe dazu einen API-Aufruf an den Node health durch.

Die Ausgabe sollte in etwa wie folgt aussehen:

{
    "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."
              }
          ]
      }
  }
}

Die Antwort zeigt als gateway_status für den primären Master-Container den gateway_statusunregistered an, da der WhatsApp Business API-Client noch nicht registriert wurde.

Schritt 7: Den WhatsApp Business API-Client registrieren

Du kannst den WhatsApp Business API-Client über einen API-Aufruf an den account-Node registrieren.

Schritt 8: Eine zweite Systemdiagnose durchführen

Führe auf dem WhatsApp Business API-Client eine zweite Systemdiagnose durch. Sende dazu nach Abschluss der Registrierung einen API-Aufruf an den health-Node und stelle sicher, dass einer der Coreapp-Container den gateway_statusconnected aufweist.

Die Ausgabe sollte in etwa wie folgt aussehen:

{
    "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"
        }
    }
}

Hinweis: Im Hochverfügbarkeitsmodus wird nur eine Coreapp (in diesem Beispiel wacore1) mit dem WhatsApp-Server verbunden. Alle anderen Nodes, einschließlich des primären Masters, weisen den gateway_statusdisconnected auf. Wenn wacore1 ausfällt, wird er durch wacore2 ersetzt und mit dem WhatsApp-Server verbunden, um die Hochverfügbarkeit aufrechtzuerhalten.

Jetzt hast du den WhatsApp Business API-Client im Hochverfügbarkeitsmodus eingerichtet. In diesem Modus kann jeweils immer nur eine Coreapp eine Verbindung zum WhatsApp-Server herstellen, um Nachrichten zu senden. Sollen mehrere Coreapps gleichzeitig Nachrichten senden, um den Nachrichtendurchsatz zu erhöhen, befolge die Schritte im nachstehenden Abschnitt Einrichten eines Hochverfügbarkeits-Multiconnect-Clusters.

Einrichten eines Hochverfügbarkeits-Multiconnect-Clusters

Schritt 1: Zwei Shards einrichten

Verwende den Shards-Endpunkt, um zwei Shards einzurichten. Eine HTTP-Antwort mit dem Status 201 Created sollte angezeigt werden.

Schritt 2: Eine Systemdiagnose durchführen

Du kannst auf dem WhatsApp Business API-Client eine Systemdiagnose durchführen. Sende dazu einen API-Aufruf an den health-Node.

Die Ausgabe sollte in etwa wie folgt aussehen:

{
    "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"
        }
    }
}

Hinweis: Im Multiconnect-Modus mit zwei Shards werden zwei Coreapps (in diesem Beispiel wacore1 und wacore2) mit dem WhatsApp-Server verbunden. Der primäre Master (in diesem Beispiel master2) wird ebenfalls mit dem WhatsApp-Server verbunden.

Schritt 3: Eine dritte Coreapp starten, um Hochverfügbarkeit aufrechtzuerhalten

In diesem Beispiel verfügst du bisher über zwei Coreapp-Container, zwischen denen die Nachrichtenlasten aufgeteilt werden. Fällt jedoch einer der Coreapp-Container aus, schlägt der Sendevorgang für die Hälfte deiner Nachrichten fehl. Um die Hochverfügbarkeit in diesem neuen Multiconnect-Setup aufrechtzuerhalten, kannst du eine dritte Coreapp starten, um Ausfallsicherheit für eine Coreapp zu schaffen. Diese Lösung entspricht ungefähr dem Diagramm aus der Einführung von Multiconnect.

Führe zum Starten des dritten Coreapp-Containers den folgenden Befehl aus:

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

Die Ausgabe sollte in etwa wie folgt aussehen:

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

Schritt 4: Eine zweite Systemdiagnose durchführen

Führe eine weitere Systemdiagnose durch, um zu bestätigen, dass alle Nodes richtig ausgeführt werden. Sende dazu einen API-Aufruf an den health-Node.

Die Ausgabe sollte in etwa wie folgt aussehen:

{
    "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"
        }
    }
}

Der neue Coreapp-Container (in diesem Beispiel wacore3) hat nun die Funktion eines Standby-Containers, ist aktuell aber nicht mit dem WhatsApp-Server verbunden. Wenn wacore1 oder wacore2 ausfällt, wird wacore3 mit dem WhatsApp-Server verbunden, um die Gesamtanzahl der Shards von 2 beizubehalten.

Aktualisieren des WhatsApp Business API-Clients

Während des Upgrade-Prozesses musst du mit Ausfallzeiten rechnen.

Es wird dringend empfohlen, vor dem Upgrade eine Sicherung der aktuellen Anwendungseinstellungen durchzuführen, damit die Anwendung anschließend schnell wieder einsatzbereit ist. Beachte dabei die Dokumentation zu Sicherung und Wiederherstellung.

Es ist grundsätzlich ratsam, Aktualisierungen zu Zeiten mit geringer Aktivität durchzuführen.

Schritt 1: Die WA_API_VERSION-Umgebungsvariable in die neue Version ändern

Die WA_API_VERSION-Umgebungsvariable sollte auf die neue Version geändert werden. Verwende hierfür:

export WA_API_VERSION=new-whatsapp-version

Schritt 2: Die Docker-Container neu starten

Starte die Docker-Container neu, indem du folgenden Code ausführst:

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

Für MySQL-Datenbanknutzer*innen, die ein Upgrade auf Version v2.23.x und höher durchführen

steht dir nun ein Datenbankaktualisierungsdienst zur Verfügung, mit dem du deine Datenbank bei ausgeführter Anwendung aktualisieren kannst, um Ausfallzeiten zu vermeiden.

Schritt 1: Die Konfigurationsdatei herunterladen

Die Datei dbupgrade-compose.yml beinhaltet Felder mit Angaben zur Containerversion.

Beispiel:

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

Schritt 2: Den Container starten

Führe zur Aktualisierung einer Installation den Container „dbupgrade-service“ aus, während für die WA_API_VERSION-Umgebungsvariable die aktuellste Version angegeben ist:

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

Hinweis: Wenn du mit einer Orchestrierung arbeitest, mit welcher der Container beim Beenden unabhängig vom Exit-Code neu gestartet wird, solltest du die Umgebungsvariable EXIT_ON_SUCCESS auf FALSE setzen, wenn du den Dienst startest. So vermeidest du, dass der Container beendet wird, wenn der Exit-Code 0 lautet.

Schritt 3: Warten, bis das Upgrade abgeschlossen ist

Verläuft die Datenbankaktualisierung erfolgreich, wird der Container mit dem Code 0 beendet. Du kannst mit dem folgenden Docker-Befehl den Status nachverfolgen:

docker wait your-database-upgrade-container-name

Hiermit wird der Exit-Code des dbupgrade-service-Containers ausgegeben.

Schritt 4: Coreapp- und Webapp-Container neu starten

Starte die Coreapp- und Webapp-Docker-Container neu und setze dabei die Umgebungsvariable WA_API_VERSION auf die aktuelle Version:

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

Deinstallation des WhatsApp Business API-Client

Es wird dringend empfohlen, die aktuellen Anwendungseinstellungen vor der Deinstallation zu sichern. Beachte dabei die Dokumentation zu Sicherung und Wiederherstellung.

Wenn du deine Entwicklungsumgebung durch Entfernen aller Container zurücksetzen musst, führe den folgenden Befehl über das Verzeichnis aus, das die Datei multiconnect-compose.yml enthält:

docker-compose -f multiconnect-compose.yml down

Um zusätzlich zu den Containern alle in der Datei multiconnect-compose.yml definierten Volumes zu entfernen, führe down mit dem Parameter -v aus:

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

Problembehebung

Führe zur Sammlung von Protokollen aus allen Containern den folgenden Befehl aus:

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

Hänge zum Sammeln von Protokollen eines bestimmten Dienstes den Dienstnamen (waweb, master1, wacore1) an den docker-compose logs-Befehl an:

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

Du findest die Protokolle in der Datei debug_output.txt im aktuellen Verzeichnis.

Diese Software verwendet Code von FFmpeg, der unter der LGPLv2.1 lizenziert ist. Die dazugehörige Quelle kann hier heruntergeladen werden.