Configuração de produção: alta disponibilidade e multiconexão

Este documento mostra como configurar um cluster com alta disponibilidade na produção. Também fornece orientações sobre como habilitar o recurso de multiconexão e indica as mudanças necessárias para um cluster de multiconexão com alta disponibilidade.

Antes de iniciar qualquer uma das configurações, consulte nossos requisitos.

Veja o que é preciso para configurar um cluster com alta disponibilidade:

1. Criar um diretório biz para os scripts de configuração
2. Obter os arquivos de configuração do cliente da WhatsApp Business API
3. Definir as variáveis de ambiente do banco de dados
4. Configurar o volume de mídia local
5. Iniciar o cliente da WhatsApp Business API
6. Verificar se os contêineres estão funcionando
7. Fazer uma verificação de integridade
8. Registrar o cliente da WhatsApp Business API
9. Fazer uma nova verificação de integridade

Veja o que é preciso para configurar um cluster de multiconexão com alta disponibilidade:

1. Configurar dois fragmentos
2. Fazer uma verificação de integridade
3. Iniciar um terceiro Coreapp para manter a alta disponibilidade
4. Fazer uma nova verificação de integridade

Depois de concluir a configuração da sua instância, você pode atualizá-la. Para desinstalar o cliente, siga estas etapas.

Antes de começar

Você precisará do seguinte:

• Diversos servidores de computação para executar os vários componentes do cliente da WhatsApp Business API (por exemplo, Webapp, Master e Coreapp)

  • Para conhecer os requisitos do sistema, consulte Quais são os requisitos do sistema do servidor para executar o cliente da WhatsApp Business API? nas perguntas frequentes.
  • Para aplicar uma configuração de alta disponibilidade na produção, recomendamos pelo menos 1 máquina para o contêiner do Webapp, 2 para os contêineres do Coreapp e 2 para os contêineres do Master. Os carregamentos nos Masters são leves, e você pode alocar tanto os contêineres do Coreapp quanto os do Master no mesmo host.
• Instale o Docker Desktop e o Docker Compose.
• Um servidor de banco de dados autônomo que executa um processo MySQL ou PostgreSQL

  • O servidor de banco de dados não deve ser executado em nenhum outro servidor de computação que hospeda o cliente da WhatsApp Business API e precisa estar a apenas alguns milissegundos de latência dos outros servidores de computação.

• Um sistema de arquivos compartilhado (por exemplo, NFS) montado em um diretório local em todos os hosts do Webapp, Master e Coreapp, caso você queira trabalhar com o envio e o recebimento de mensagens de mídia

  • É preciso definir 755 como o modo de arquivo no caminho de montagem e em todos os subdiretórios relacionados.

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

Configurar um cluster com alta disponibilidade

Etapa 1: criar um diretório biz para os scripts de configuração

Na localização que você preferir, execute o seguinte código do cliente da WhatsApp Business API:

mkdir ~/biz; cd ~/biz;

Etapa 2: obter os arquivos de configuração do cliente da WhatsApp Business API

Clone os arquivos de configuração prod-multiconnect-compose.yml e db.env do diretório Instalação do repositório do GitHub WhatsApp-Business-API-Setup-Scripts para o diretório ~/biz que você criou na Etapa 1.

Etapa 3: definir as variáveis de ambiente do banco de dados

Altere as variáveis de ambiente do banco de dados no arquivo db.env do diretório ~/biz para refletir sua configuração 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

Etapa 4: configurar o volume de mídia local

O volume de mídia local (whatsappMedia:/usr/local/wamedia por padrão) definido no arquivo prod-docker-compose.yml é usado para armazenar arquivos de mídia. Por padrão, o volume é montado em um diretório na máquina do Docker. Como alternativa, você pode montar o volume de mídia em um diretório de host. Para alterar o ponto de montagem do volume de mídia, modifique a definição do volume dentro da seção services de whatsappMedia para o caminho do diretório de host usado por você.

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

Etapa 5: iniciar o cliente da WhatsApp Business API

Para iniciar o cliente da WhatsApp Business API com 1 contêiner do Webapp, 2 contêineres do Master e 2 contêineres do Coreapp, como no diagrama de introdução à alta disponibilidade, use os seguintes comandos com as alterações necessárias para seu ambiente (ou seja, nomes de host, nomes de usuário de host e caminhos locais):

# 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

Para resumir, os comandos acima resultarão nas seguintes ações:

• Copiar os arquivos de configuração prod-multiconnect-compose.yml e db.env para todos os hosts do Webapp (your-webapp-hostname nesse exemplo) e iniciar o serviço waweb nesses hosts
• Copiar os arquivos de configuração prod-multiconnect-compose.yml e db.env para todos os hosts do Master (your-master1-hostname e your-master2-hostname nesse exemplo) e iniciar o serviço Master nesses hosts
• Copiar os arquivos de configuração prod-multiconnect-compose.yml e db.env para todos os hosts do Coreapp (your-coreapp1-hostname e your-coreapp2-hostname nesse exemplo) e iniciar o serviço wacore nesses hosts

Etapa 6: verificar se os contêineres estão funcionando

É possível verificar se todos os contêineres têm um status RUNNING executando o seguinte:

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

Etapa 7: fazer uma verificação de integridade

É possível fazer a verificação de integridade na WhatsApp Business API do cliente por meio de uma chamada de API para o nó health.

A saída terá aparência semelhante a esta:

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

A resposta mostra o gateway_status de unregistered porque o cliente da WhatsApp Business API ainda não foi registrado.

Etapa 8: registrar o cliente da WhatsApp Business API

Você pode registrar o cliente da WhatsApp Business API por meio de uma chamada de API para o nó account.

Etapa 9: fazer uma nova verificação de integridade

Realize uma nova verificação de integridade no cliente da WhatsApp Business API. Faça uma chamada de API para o nó health depois de concluir o registro e verifique se um dos contêineres do Coreapp tem um gateway_status de connected.

A saída terá aparência semelhante a esta:

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

Observação: no modo de alta disponibilidade, apenas um Coreapp (your-coreapp1-hostname:753efb1cf72c nesse exemplo) será conectado ao servidor do WhatsApp. Todos os outros nós, incluindo o Master principal, terão um gateway_status de disconnected. Se o your-coreapp1-hostname:753efb1cf72c parar de funcionar, your-coreapp2-hostname:75d7355eaaaa o substituirá, e será feita a conexão com o servidor do WhatsApp para manter a alta disponibilidade.

Agora, o cliente da WhatsApp Business API está configurado no modo de alta disponibilidade. Nesse modo, somente um Coreapp conseguirá se conectar ao servidor do WhatsApp por vez para enviar mensagens. Caso você queira ter vários Coreapps enviando mensagens por vez para aumentar a taxa de transferência, siga as etapas descritas na seção Configurar um cluster de multiconexão com alta disponibilidade abaixo.

Configurar um cluster de multiconexão com alta disponibilidade

Etapa 1: configurar dois fragmentos

Use o ponto de extremidade de fragmentos para configurar dois fragmentos. Você verá uma resposta HTTP com status 201 Created.

Etapa 2: fazer uma verificação de integridade

É possível fazer a verificação de integridade no cliente da WhatsApp Business API por meio de uma chamada de API para o nó health a fim de verificar se todos os nós estão funcionando corretamente.

A saída terá aparência semelhante a esta:

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

Observação: no modo de multiconexão com 2 fragmentos, serão conectados 2 Coreapps (your-coreapp1-hostname:753efb1cf72c e your-coreapp2-hostname:75d7355eaaaa nesse exemplo) ao servidor do WhatsApp. Além disso, o Master principal (your-master2-hostname:8dd3f5bea27d nesse exemplo) será conectado ao mesmo servidor.

Etapa 3: iniciar um terceiro Coreapp para manter a alta disponibilidade

Até o momento, neste exemplo, você tem dois contêineres do Coreapp, e o carregamento de mensagens se divide entre eles. Entretanto, caso um dos contêineres pare de funcionar, ocorrerá falha na metade dos envios de mensagens. Para manter a alta disponibilidade na nova configuração de multiconexão, você pode iniciar um terceiro Coreapp em um novo host do Coreapp (

nesse exemplo) para suportar a falha em 1 Coreapp, como no diagrama mostrado na introdução à multiconexão.

Para iniciar o terceiro contêiner do Coreapp, execute o seguinte 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

Etapa 4: fazer uma nova verificação de integridade

Realize outra verificação de integridade por meio de uma chamada de API para o nó health, com objetivo de conferir se todos os nós estão funcionando corretamente.

A saída terá aparência semelhante a esta:

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

Agora, o novo contêiner do Coreapp (your-coreapp3-hostname:23b50199bec2 nesse exemplo) funcionará como um contêiner reserva. No entanto, neste momento, ele não está conectado ao servidor do WhatsApp. Se algum dos outros 2 contêineres de Coreapp conectados parar de funcionar, o terceiro se conectará ao servidor do WhatsApp para manter a contagem geral de fragmentos em 2.

Diretrizes e boas práticas

Número de Webapps

Recomendamos no mínimo 2 Webapps para suportar o envio de 100 a 150 mensagens por segundo. Se quiser alcançar a alta disponibilidade para o Webapp, execute os contêineres do Webapp em mais de 2 hosts e hospede-os com um balanceador de carga (como HAProxy, Nginx ou ELB). Em vez de acessar os pontos de extremidade do cliente da WhatsApp Business API por https://your-webapp-hostname:your-webapp-port/, use https://your-load-balancer-name:your-load-balancer-port/.

Números de Masters

Recomendamos ter pelo menos 3 Masters em execução em diferentes hosts. Não será necessário ter mais de 3 Masters na produção, independentemente de quantos fragmentos você tiver. Os carregamentos nos Masters são leves, e você pode alocá-los com contêineres do Coreapp.

Números de Coreapps

É recomendável ter shard_number + X Coreapps sendo executados em diferentes hosts para suportar X falhas no host.

Atualização do cliente da WhatsApp Business API

A variável de ambiente WA_API_VERSION precisa ser atualizada para a versão mais recente. Execute os seguintes comandos com as alterações necessárias para seu ambiente (ou seja, nomes de host, nomes de usuário de host e caminhos locais):

# 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

Para usuários do banco de dados MySQL que estão atualizando para 2.23.x ou versão posterior

Agora, você pode usar um serviço para atualizar o banco de dados enquanto o app continua em execução, evitando o tempo de inatividade.

Etapa 1: baixar o arquivo de configuração

O arquivo dbupgrade-compose.yml tem campos que indicam a versão do contêiner.

Exemplo:

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

Etapa 2: inicializar o contêiner

Para atualizar uma instalação, inicialize o contêiner dbupgrade-service com a variável de ambiente WA_API_VERSION definida como a versão mais recente:

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

Observação: se você estiver usando uma orquestração que reinicia o contêiner na saída, independentemente do código de saída, inicialize o serviço com a variável de ambiente EXIT_ON_SUCCESS definida como FALSE. Isso evitará a saída do contêiner quando o código de saída for 0.

Etapa 3: permitir que a atualização seja concluída

Se a atualização do banco de dados for bem-sucedida, o contêiner sairá com o código 0. É possível usar o seguinte comando do Docker para acompanhar o status:

docker wait your-database-upgrade-container-name

Com isso, o código de saída do contêiner dbupgrade-service será criado.

Etapa 4: reiniciar os contêineres do Coreapp e do Webapp

Reinicie os contêineres do Docker do Coreapp e do Webapp com a variável de ambiente WA_API_VERSION definida como a versão mais recente:

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

Para usuários do cliente da WhatsApp Business API que estão atualizando para 2.29.3 ou versão superior

Se estiver atualizando v2.29.1, v2.29.2ou tiver encontrado problemas durante a atualização para essas versões e teve que reverter para estabilidade, recomendamos que você atualize para v2.29.3. Depois, execute o seguinte comando no contêiner do Docker do Webapp:

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

A menos que você o tenha alterado, o diretório de mídia padrão será /usr/local/wamedia.

Observação:

• Como esse comando pode demorar um pouco para ser concluído com base no tamanho do volume de mídia que já existe, recomendamos que ele seja iniciado assim que você fizer a atualização durante a janela de manutenção.
• Esse comando apenas modifica a propriedade de volumes de mídia em segundo plano (não há impacto/inatividade para operações de mídia nem latência/desempenho durante a execução).
• Esse é um caminho de atualização único para corrigir problemas de compatibilidade com versões anteriores em v2.29.1 e v2.29.2.

Desinstalar o cliente da WhatsApp Business API

Se você precisar redefinir seu ambiente de desenvolvimento removendo todos os contêineres, use os seguintes comandos com as alterações necessárias (ou seja, nomes de host, nomes de usuário de host e caminhos locais):

# 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

Solução de problemas

Para coletar registros de todos os contêineres no host, execute o seguinte comando:

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

Para coletar registros de um serviço específico, anexe o nome do serviço (por exemplo, waweb, master1, wacore1) ao comando docker-compose logs.

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

Os registros podem ser encontrados no arquivo debug_output.txt no diretório atual.