Produktions-Setup: Einzelinstanz

In diesem Dokument wird gezeigt, wie du eine Einzelinstanz des WhatsApp Business API-Client in einer Produktionsumgebung einrichtest.

Prüfe zum Abschluss deiner Ersteinrichtung unsere Anforderungen und befolge diese Schritte:

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. Die Variablen der Datenbankumgebung festlegen
5. Das lokale Medienvolume einrichten
6. Den WhatsApp Business API-Client starten
7. Verifizieren, ob die Container ausgeführt werden
8. Eine Systemdiagnose durchführen
9. Den WhatsApp Business API-Client registrieren
10. 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

Voraussetzungen:

• Docker Desktop und Docker Compose installieren
• Ein Server, auf dem der WhatsApp Business API-Client ausgeführt wird Informationen zu den Systemvoraussetzungen findest du in den „Häufig gestellten Fragen“ unter Wie lauten die Systemvoraussetzungen für den Server zur Ausführung des WhatsApp Business API-Client?
• Ein Standalone-Datenbankserver zur Ausführung eines MySQL- oder PostgreSQL-Prozesses Die Latenzzeit zwischen dem Datenbankserver und dem Server, auf dem der WhatsApp Business API-Client gehostet ist, sollte nur wenige Millisekunden betragen.

Erst-Setup des WhatsApp Business API-Client

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

Klone die Konfigurationsdateien prod-docker-compose.yml und db.env aus dem Verzeichnis Installation im GitHub-Repository WhatsApp-Business-API-Setup-Scripts in das ~/biz-Verzeichnis, das du in Schritt 1 erstellt hast.

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: Die Datenbankumgebungsvariablen festlegen

Ändere die Datenbankumgebungsvariablen in der Datei db.env unter dem Verzeichnis ~/biz entsprechend deiner MySQL/PostgreSQL-Konfiguration.

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

Schritt 5: Das lokale Medienvolume einrichten

Das lolale Medienvolume (standardmäßig whatsappMedia:/usr/local/wamedia), das in der Datei prod-docker-compose.yml definiert ist, wird zum Speichern von Mediendateien verwendet. Das Volume ist standardmäßig in einem Verzeichnis des Docker-Computers gemountet. Du kannst das Medienvolume auch in einem Host-Verzeichnis mounten. Um den Mount-Punkt des Medienvolume zu ändern, ändere die Volumedefinition im Bereich services von whatsappMedia in den Pfad des Hostverzeichnisses, das du verwendest.

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

Schritt 6: Den WhatsApp Business API-Client starten

Führe zum Starten des WhatsApp Business API-Client mit einem Webapp-Container und einem Coreapp-Container Folgendes aus:

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

Die Ausgabe sollte in etwa wie folgt aussehen:

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

Schritt 7: Verifizieren, ob die Container ausgeführt werden

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

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

Die Ausgabe sollte in etwa wie folgt aussehen:

     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

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

Schritt 8: Eine Systemdiagnose durchführen

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": {
        "gateway_status": "unregistered"
    }
}

Die Antwort zeigt als gateway_statusgateway_statusunregistered an, da der WhatsApp Business API-Client noch nicht registriert wurde.

Schritt 9: Den WhatsApp Business API-Client registrieren

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

Schritt 10: Eine zweite Systemdiagnose durchführen

Führe auf dem WhatsApp Business API-Client eine zweite Systemdiagnose durch. Führe dazu nach Abschluss der Registrierung einen API-Aufruf an den Node health durch.

Die Ausgabe sollte in etwa wie folgt aussehen:

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

Der gateway_statusconnected gibt an, dass der Coreapp-Container eine Verbindung zum WhatsApp-Server herstellen kann, um Kontakte zu prüfen und Nachrichten zu senden.

Aktualisieren des WhatsApp Business API-Clients

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 prod-docker-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, während für die Umgebungsvariable WA_API_VERSION die aktuellste Version angegeben ist:

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

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

Wenn du ein Upgrade von v2.29.1, v2.29.2 durchführst oder beim Upgrade auf diese Versionen Probleme aufgetreten sind und du aus Stabiliätsgründen ein Rollback durchführen musstest, empfehlen wir dir ein Upgrade auf v2.29.3 durchzuführen und dann auf dem Webapp-Docker-Container den folgenden Befehl ausführen:

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

Sofern du das standardmäßige Medienverzeichnis nicht geändert hast, lautet dieses /usr/local/wamedia.

Hinweis:

• Da die Ausführung dieses Befehls aufgrund der Größe des bereits vorhandenen Medienvolume eine Weile dauern kann, empfehlen wir, diesen Befehl zu starten, sobald du während des Wartungsfensters ein Upgrade durchführst.
• Mit diesem Befehl wird nur der Besitz von Medienvolumes im Hintergrund geändert (es kommt während der Ausführung nicht zu Auswirkungen/Ausfallzeiten für Medienvorgänge oder Latenzproblemen/Leistungsbeeinträchtigen).
• Dies ist ein einmaliger Upgrade-Pfad zur Behebung von Problemen mit der Abwärtskompatibilität in v2.29.1 und v2.29.2.

Deinstallation des WhatsApp Business API-Client

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

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

Die Ausgabe sollte in etwa wie folgt aussehen:

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

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

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

Problembehebung

Für den Fall, dass WADebug nicht verwendet werden kann oder bei Ausführung des Tools Fehler ausgegeben werden, führe zur Sammlung von Protokollen aus allen Containern den folgenden Befehl aus:

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

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

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

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