Configurazione di produzione: High Availability e Multiconnect

Questo documento mostra come configurare un cluster High Availability in produzione. Fornisce inoltre tutte le indicazioni necessarie per abilitare Multiconnect insieme alle modifiche richieste per un cluster Multiconnect ad High Availability.

Prima di iniziare una qualsiasi di queste configurazioni, consulta i nostri requisiti.

Per configurare un cluster ad High Availability:

1. Crea una directory biz per gli script di configurazione
2. Ottieni i file di configurazione del client dell'API di WhatsApp Business
3. Imposta le variabili d'ambiente del database
4. Configura il volume del contenuto multimediale locale
5. Avvia il client dell'API di WhatsApp Business
6. Verifica che i contenitori siano in esecuzione
7. Effettua un controllo integrità
8. Registra il client dell'API di WhatsApp Business
9. Esegui un secondo controllo integrità

Per configurare un cluster Multiconnect ad High Availability:

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à

Una volta configurata completamente la tua istanza, puoi scegliere di aggiornarla. Per disinstallare il client, segui questi passaggi.

Prima di iniziare

Ecco cosa ti servirà:

• Più server di calcolo per eseguire i vari componenti del client dell'API di WhatsApp Business (ad es. Webapp, Master e Coreapp)

  • Per i requisiti di sistema, consulta Quali sono i requisiti di sistema del server per eseguire il client dell'API di WhatsApp Business? nelle FAQ.
  • Per una configurazione High Availability in produzione, consigliamo almeno 1 macchina per il contenitore Webapp, 2 macchine per i contenitori Coreapp e 2 macchine per i contenitori Master. I carichi sui Master sono leggeri e si potrebbero collocare i container Master e Coreapp sullo stesso host.
• Installa Docker Desktop e Docker Compose.
• Un server di database standalone che esegue un processo MySQL o PostgreSQL

  • Il server di database non deve essere eseguito su uno qualsiasi degli altri server di calcolo che ospitano il client dell'API di WhatsApp Business; tra esso e gli altri server di calcolo dovrebbero intercorrere solo pochi millisecondi di latenza.

• Un file system condiviso (ad es. NFS) montato su una directory locale su tutti gli host Webapp, Master e Coreapp, se vuoi supportare l'invio e la ricezione di messaggi multimediali

  • Assicurati che 755 sia impostato come modalità file sul percorso di montaggio e su tutte le sue sottodirectory.

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

Configurazione di un cluster ad 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

Clona i file di configurazione prod-multiconnect-compose.yml e db.env dalla directory di installazione del repository GitHub WhatsApp-Business-API-Setup-Scripts nella directory ~/biz che hai creato nel Passaggio 1.

Passaggio 3: impostazione delle variabili d'ambiente del database

Modifica le variabili d'ambiente del database nel file db.env nella directory ~/biz per riflettere la tua configurazione 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

Passaggio 4: configurazione del volume dei contenuti multimediali locali

Il volume dei contenuti multimediali locali (whatsappMedia:/usr/local/wamedia per impostazione predefinita) definito nel file prod-docker-compose.yml viene utilizzato per la memorizzazione dei file multimediali. Per impostazione predefinita, il volume viene montato su una directory nella macchina Docker. In alternativa, puoi scegliere di montare il volume dei contenuti multimediali su una directory host. Per modificare il punto di montaggio del volume dei contenuti multimediali, modifica la definizione di volume all'interno della sezione services da whatsappMedia al percorso della directory host utilizzata.

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

Passaggio 5: avvio del client dell'API di WhatsApp Business

Per avviare il client dell'API di WhatsApp Business con 1 contenitore Webapp, 2 contenitori Master e 2 contenitori Coreapp simili al diagramma di introduzione High Availability, usa i seguenti comandi con le modifiche necessarie per il tuo ambiente (ovvero nomi host, nomi utente host e percorsi locali):

# 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

In sintesi, con i comandi sopra riportati verranno eseguite le azioni seguenti:

• copia dei file di configurazione prod-multiconnect-compose.yml e db.env su tutti gli host Webapp (your-webapp-hostname in questo esempio) e avvio del servizio waweb su questi host;
• copia dei file di configurazione prod-multiconnect-compose.yml e db.env su tutti gli host Master (your-master1-hostname e your-master2-hostname in questo esempio) e avvio del servizio Master su questi host;
• copia dei file di configurazione prod-multiconnect-compose.yml e db.env su tutti gli host Coreapp (your-coreapp1-hostname e your-coreapp2-hostname in questo esempio) e avvio del servizio wacore su questi host.

Passaggio 6: verifica che i contenitori siano in esecuzione

Puoi controllare che tutti i contenitori abbiano uno stato RUNNING eseguendo:

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

Passaggio 7: esecuzione di un controllo integrità

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

L'output risultante dovrebbe essere simile al seguente:

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

Passaggio 8: 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 9: 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": {
        "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

Nota: in modalità High Availability, solo un Coreapp (your-coreapp1-hostname:753efb1cf72c in questo esempio) viene connesso al server WhatsApp, tutti gli altri nodi, compreso il Master primario, presenteranno disconnected come gateway_status. Se your-coreapp1-hostname:753efb1cf72c smette di funzionare, your-coreapp2-hostname:75d7355eaaaa 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à

Per verificare che tutti i nodi siano correttamente in esecuzione, 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": {
        "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    

Nota: in modalità Multiconnect con 2 shard, saranno connessi al server WhatsApp 2 Coreapp (your-coreapp1-hostname:753efb1cf72c e your-coreapp2-hostname:75d7355eaaaa in questo esempio) e il Master primario (your-master2-hostname:8dd3f5bea27d 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 su un nuovo host Coreapp (

in questo esempio) così da poter tollerare 1 errore Coreapp, in modo simile al diagramma mostrato nella Introduzione a Multiconnect.

Per avviare il terzo contenitore Coreapp, esegui questo comando:

# 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

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

Il nuovo contenitore Coreapp (your-coreapp3-hostname:23b50199bec2 in questo esempio) ora agisce da contenitore di standby, ma non è attualmente connesso al server WhatsApp. Se uno degli altri 2 contenitori Coreapp connessi smette di funzionare, il terzo contenitore si connette al server WhatsApp per mantenere un numero totale di shard pari a 2.

Linee guida e best practice

Numero di Webapp

Per supportare 100-150 messaggi/sec., sono consigliati almeno 2 Webapp. Se desideri ottenere High Availability per Webapp, puoi eseguire i contenitori Webapp su più di 2 host e avvalerti di un servizio di bilanciamento del carico come HAProxy, Nginx o ELB. Invece di accedere agli endpoint del client dell'API di WhatsApp Business tramite https://your-webapp-hostname:your-webapp-port/, dovresti usare https://your-load-balancer-name:your-load-balancer-port/.

Numero di Master

È consigliabile avere 3 Master in esecuzione su diversi host. Non è necessario avere più di 3 Master in produzione, indipendentemente dal numero di shard di cui si dispone. I carichi sui Master sono leggeri, pertanto potresti collocarli insieme ai contenitori Coreapp.

Numero di Coreapp

È consigliabile avere shard_number + X Coreapp in esecuzione su diversi host per poter tollerare X guasti dell'host.

Aggiornamento del client dell'API di WhatsApp Business

La variabile d'ambiente WA_API_VERSION deve essere aggiornata al nuovo numero di versione. Esegui i seguenti comandi con le modifiche necessarie per il tuo ambiente (ovvero nomi host, nomi utente host e percorsi locali):

# 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

Per gli utenti del database MySQL che eseguono l'aggiornamento alla versione 2.23.x o 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 d'ambiente WA_API_VERSION impostata sull'ultima versione:

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

Nota: se stai utilizzando un'orchestrazione che riavvia il contenitore all'uscita indipendentemente dal codice di uscita, inizia il servizio con la variabile d'ambiente EXIT_ON_SUCCESS impostata su FALSE per evitare di uscire 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 d'ambiente WA_API_VERSION impostata sull'ultima versione:

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

Per gli utenti del client dell'API di WhatsApp Business che eseguono l'aggiornamento alla versione 2.29.3 e successive

Se stai eseguendo l'aggiornamento dalla versione v2.29.1, v2.29.2o hai riscontrato problemi durante l'aggiornamento a quelle versioni e hai dovuto eseguire il ripristino per la stabilità, è consigliabile eseguire l'aggiornamento alla versione v2.29.3, quindi eseguire il seguente comando nel contenitore Docker Webapp:

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

A meno che tu non abbia modificato la directory dei contenuti multimediali, quella predefinita è /usr/local/wamedia.

Nota:

• Poiché il completamento di questo comando può richiedere del tempo in base alle dimensioni del volume dei contenuti multimediali preesistenti, è consigliabile avviare questo comando non appena si esegue l'aggiornamento durante la finestra di manutenzione.
• Questo comando modifica solo la proprietà dei volumi dei contenuti multimediali in background (non è previsto alcun impatto/tempo di inattività per operazioni multimediali o latenza/prestazioni durante l'esecuzione).
• Questo è un percorso di aggiornamento unico per risolvere i problemi di compatibilità con le versioni precedenti in v2.29.1 e v2.29.2.

Disinstallazione del client dell'API di WhatsApp Business

Se devi reimpostare il tuo ambiente di sviluppo rimuovendo tutti i contenitori, usa i seguenti comandi con le modifiche necessarie al tuo ambiente (ovvero nomi host, nomi utente host e percorsi locali):

# 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

Risoluzione dei problemi

Per acquisire i registri da tutti i contenitori su un host, esegui il comando seguente:

EXTERNAL_HOSTNAME=$host_to_collect_logs docker-compose -f /local/path/prod-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.

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

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