API On-Premises della piattaforma WhatsApp Business

Configurazione sviluppatore: High Availability e Multiconnect

Questo documento illustra come configurare un cluster High Availability su una macchina sviluppatore. Fornisce inoltre tutte le indicazioni necessarie per abilitare Multiconnect insieme alle modifiche richieste per un cluster Multiconnect a disponibilità elevata. Per una configurazione di produzione, segui le istruzioni pertinenti elencate in Configurazioni di produzione.

Prima di iniziare la procedura di configurazione, consulta la lista dei requisiti.

Per configurare un cluster High Availability, segui questa procedura:

  1. Crea una directory biz per gli script di configurazione
  2. Acquisisci i file di configurazione del client dell'API di WhatsApp Business
  3. Imposta la variabile ambientale WA_API_VERSION
  4. Avvia il client dell'API di WhatsApp Business con High Availability
  5. Verifica che i contenitori siano in esecuzione
  6. Esegui un controllo integrità
  7. Registra il client dell'API di WhatsApp Business
  8. Esegui un secondo controllo integrità

Per configurare un cluster Multiconnect, segui questa procedura:

  1. Configura due shard
  2. Esegui un controllo integrità
  3. Avvia una terza coreapp per mantenere l'High Availability
  4. Esegui un secondo controllo integrità

Dopo aver configurato completamente l'istanza, puoi scegliere di aggiornarla. Per disinstallare il client, segui questi passaggi.

Prima di iniziare

Se hai seguito le istruzioni Configurazione sviluppatore: istanza singola per configurare un client dell'API di WhatsApp Business su una macchina per sviluppatori, segui la Guida alla migrazione prima di continuare con il resto di questo documento.

Il contenuto di questa guida si basa sul presupposto di una nuova installazione.

Prima di iniziare, dovrai completare le seguenti azioni:

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.

Altri prerequisiti

Assicurati di configurare un account test in locale in un ambiente di sviluppo. Servirà per uno sviluppo rapido e per testare nuove uscite. È inoltre vivamente consigliato leggere la Guida su disponibilità e scalabilità per saperne di più su High Availability e Multiconnect.

Configurazione di un cluster High Availability

Passaggio 1: creazione di una directory biz per gli script di configurazione

Esegui il codice seguente nella posizione che preferisci per il client dell'API di WhatsApp Business:

mkdir ~/biz; cd ~/biz;

Passaggio 2: acquisizione dei file di configurazione del client dell'API di WhatsApp Business

I file di configurazione del client dell'API di WhatsApp Business si trovano nella directory GitHub WhatsApp-Business-API-Setup-Scripts. Puoi configurare il tuo client dell'API di WhatsApp Business con un'istanza di database MySQL o Postgres.

Passaggio 3: impostazione della variabile ambientale WA_API_VERSION

La variabile ambientale WA_API_VERSION deve essere impostata sulla versione corrente mediante:

export WA_API_VERSION=current-whatsapp-version

Passaggio 4: avvio del client dell'API WhatsApp Business con High Availability

Per avviare un cluster High Availability con 1 contenitore del database, 1 contenitore Webapp, 2 contenitori Master e 2 contenitori Coreapp in background analogamente al diagramma mostrato in Introduzione ad High Availability, esegui il comando seguente:

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

L'output risultante dovrebbe essere simile al seguente:

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

Passaggio 5: verifica che i contenitori siano in esecuzione

Puoi controllare che tutti i contenitori abbiano uno stato UP eseguendo il seguente comando:

docker-compose -f multiconnect-compose.yml ps

L'output risultante dovrebbe essere simile al seguente:

      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

Per impostazione predefinita, il contenitore Webapp verrà eseguito sulla porta 9090 e il contenitore del database verrà eseguito sulla porta 33060.

Passaggio 6: esecuzione di un controllo integrità

Puoi scaricare e configurare la nostra raccolta Postman per interagire con l'API di WhatsApp Business se non desideri utilizzare la riga di comando.

Puoi eseguire un controllo integrità sul client dell'API di WhatsApp Business mediante una chiamata API al nodo health.

L'output risultante dovrebbe essere simile al seguente:

{
    "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 risposta mostra un gateway_status di unregistered come gateway_status per il contenitore Master primario perché il client dell'API di WhatsApp Business non è ancora registrato.

Passaggio 7: registrazione del client dell'API di WhatsApp Business

Puoi registrare il tuo client dell'API di WhatsApp Business mediante una chiamata API al nodo account.

Passaggio 8: esecuzione di un secondo controllo integrità

Esegui un altro controllo integrità sul client dell'API di WhatsApp Business mediante una chiamata API al nodo health al completamento della registrazione e assicurati che uno dei contenitori Coreapp abbia connected come gateway_status.

L'output risultante dovrebbe essere simile al seguente:

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

Nota: in modalità High Availability, solo un Coreapp (wacore1 in questo esempio) viene connesso al server WhatsApp, tutti gli altri nodi, compreso il Master primario, presenteranno disconnected come gateway_status. Se wacore1 smette di funzionare, wacore2 lo sostituisce connettendosi al server WhatsApp per mantenere High Availability.

Ora hai configurato il client dell'API di WhatsApp Business in modalità High Availability. In questa modalità, solo un Coreapp è in grado di connettersi al server WhatsApp per inviare messaggi in qualsiasi momento. Se desideri avere a disposizione più Coreapp in grado di inviare messaggi contemporaneamente per incrementare il throughput dei messaggi, esegui la procedura indicata nella sezione Configurazione di un cluster Multiconnect ad High Availability di seguito.

Configurazione di un cluster Multiconnect ad High Availability

Passaggio 1: configurazione di due shard

Usa l'endpoint shards per configurare 2 shard. Dovresti vedere una risposta HTTP con stato 201 Created.

Passaggio 2: esecuzione di un controllo integrità

Puoi eseguire un controllo integrità sul client dell'API di WhatsApp Business mediante una chiamata API al nodo health.

L'output risultante dovrebbe essere simile al seguente:

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

Nota: in modalità Multiconnect con 2 shard, saranno connessi al server WhatsApp 2 Coreapp (wacore1 e wacore2 in questo esempio) e il Master primario (master2 in questo esempio).

Passaggio 3: avvio di un terzo Coreapp per mantenere l'High Availability

Finora in questo esempio disponi di 2 contenitori Coreapp tra cui è ripartito il carico di messaggi. Tuttavia, se uno dei contenitori Coreapp smette di funzionare, l'invio di metà dei messaggi fallisce. Per mantenere l'High Availability in questa nuova configurazione Multiconnect, puoi avviare un terzo Coreapp in modo da compensare l'eventuale mancato funzionamento di 1 Coreapp, analogamente a quanto mostrato nel diagramma in Introduzione a Multiconnect.

Per avviare il terzo contenitore Coreapp, esegui questo comando:

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

L'output risultante dovrebbe essere simile al seguente:

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

Passaggio 4: esecuzione di un secondo controllo integrità

Esegui un altro controllo integrità per verificare che tutti i nodi funzionino correttamente mediante una chiamata API al nodo health.

L'output risultante dovrebbe essere simile al seguente:

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

Il nuovo contenitore Coreapp (wacore3 in questo esempio) funge ora da contenitore di standby, ma non è attualmente connesso al server WhatsApp. Se uno tra wacore1 e wacore2 smette di funzionare, wacore3 si connette al server WhatsApp per mantenere un numero totale di shard pari a 2.

Aggiornamento del client dell'API di WhatsApp Business

Si verificherà un tempo di inattività durante il processo di aggiornamento.

Si consiglia vivamente di eseguire il backup delle impostazioni correnti dell'app prima dell'aggiornamento per assicurarsi che il processo sia rapido ed efficace. Segui la documentazione su backup e ripristino.

È sempre consigliabile eseguire gli aggiornamenti negli orari di minor attività.

Passaggio 1: modifica della variabile ambientale WA_API_VERSION alla nuova versione

La variabile ambientale WA_API_VERSION deve essere aggiornata al nuovo numero di versione mediante:

export WA_API_VERSION=new-whatsapp-version

Passaggio 2: riavvio dei contenitori Docker

Riavvia i contenitori Docker eseguendo il seguente comando:

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

Per gli utenti del database MySQL che eseguono l'aggiornamento alla versione v2.23.x e successive

Ora puoi avvalerti di un servizio di aggiornamento database per aggiornare il tuo database mentre l'app è ancora in esecuzione, evitando così tempi di inattività.

Passaggio 1: download del file di configurazione

Il file dbupgrade-compose.yml contiene dei campi indicanti la versione dei contenitori.

Esempio:

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

Passaggio 2: avvio del contenitore

Per aggiornare un'installazione, avvia il contenitore dbupgrade-service con la variabile ambientale WA_API_VERSION impostata sull'ultima versione:

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

Nota: se utilizzi un'orchestrazione che riavvia il contenitore dopo l'uscita verificatasi indipendentemente dal codice di uscita, avvia il servizio con la variabile ambientale EXIT_ON_SUCCESS impostata su FALSE per impedire l'uscita dal contenitore quando il codice di uscita è 0.

Passaggio 3: attesa della conclusione dell'aggiornamento

Se l'aggiornamento del database è avvenuto correttamente, il contenitore uscirà con codice 0. Puoi usare il comando Docker seguente per monitorare lo stato:

docker wait your-database-upgrade-container-name

Questa operazione genererà il codice di uscita del contenitore dbupgrade-service.

Passaggio 4: riavvio dei contenitori Coreapp e Webapp

Riavvia i contenitori Docker Coreapp e Webapp con la variabile ambientale WA_API_VERSION impostata sull'ultima versione:

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

Disinstallazione del client dell'API di WhatsApp Business

Si consiglia vivamente di eseguire il backup delle impostazioni correnti dell'app prima della disinstallazione. Segui la documentazione su backup e ripristino.

Se è necessario reimpostare l'ambiente di sviluppo rimuovendo tutti i contenitori, esegui questo comando dalla directory che contiene il file multiconnect-compose.yml:

docker-compose -f multiconnect-compose.yml down

Per eliminare tutti i volumi definiti nel file multiconnect-compose.yml in aggiunta ai contenitori, esegui down con il parametro -v:

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

Risoluzione dei problemi

Per acquisire i registri da tutti i contenitori, esegui questo comando:

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

Per acquisire i registri di un determinato servizio, aggiungi il nome del servizio (ad es., waweb, master1 o wacore1) al comando docker-compose logs:

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

I registri sono disponibili nel file debug_output.txt nella directory corrente.

Questo software utilizza il codice di FFmpeg concesso in licenza ai sensi della LGPLv2.1 e il relativo codice sorgente può essere scaricato qui.