Configuração de produção: instância única

Este documento mostra como configurar uma instância única do cliente da WhatsApp Business API na produção.

Para concluir a configuração inicial, consulte os nossos requisitos e siga estas etapas:

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 a variável de ambiente WA_API_VERSION
4. Definir as variáveis de ambiente do banco de dados
5. Configurar o volume de mídia local
6. Iniciar o cliente da WhatsApp Business API
7. Verificar se os contêineres estão funcionando
8. Fazer uma verificação de integridade
9. Registrar o cliente da WhatsApp Business API
10. 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:

• Instalar o Docker Desktop e o Docker Compose
• Um servidor no qual o cliente da WhatsApp Business API é executado. 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.
• Um servidor de banco de dados autônomo que executa um processo MySQL ou PostgreSQL. O servidor de banco de dados deve estar apenas a alguns milissegundos de latência do servidor que hospeda o cliente da WhatsApp Business API.

Configuração inicial do cliente da WhatsApp Business API

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-docker-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 a variável de ambiente WA_API_VERSION

A variável de ambiente WA_API_VERSION precisa ser definida como a versão mais recente por meio de:

export WA_API_VERSION=current-whatsapp-version

Etapa 4: 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 a 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 5: 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:
  wacore:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ...          
  waweb:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ... 

Etapa 6: iniciar o cliente da WhatsApp Business API

Para iniciar o cliente da WhatsApp Business API com 1 contêiner do Webapp e 1 contêiner do Coreapp, execute:

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

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

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

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

É possível verificar se todos os contêineres têm um estado UP executando:

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

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

     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

Por padrão, o contêiner do Webapp será executado na porta 9090.

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

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

Etapa 9: 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 10: fazer uma nova verificação de integridade

Faça outra verificação de integridade no cliente da WhatsApp Business API usando uma chamada de API para o nó health após concluir o registro.

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

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

Um gateway_status de connected significa que o contêiner do Coreapp é capaz de se conectar ao servidor do WhatsApp para verificar contatos e enviar mensagens.

Atualização do cliente da WhatsApp Business API

Etapa 1: alterar a variável de ambiente WA_API_VERSION para a nova versão

A variável de ambiente WA_API_VERSION precisa ser atualizada para a versão mais recente por meio de:

export WA_API_VERSION=new-whatsapp-version

Etapa 2: reiniciar os contêineres do Docker

Reinicie os contêineres do Docker ao executar:

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

Para usuários do banco de dados MySQL que estão atualizando para v2.23.x e posteriores

Agora você pode usar um serviço de atualização do banco de dados 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:

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:

WA_API_VERSION=new-whatsapp-version docker-compose -f prod-docker-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 o ambiente de desenvolvimento removendo todos os contêineres, execute o seguinte comando no diretório que contém o arquivo prod-docker-compose.yml:

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

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

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

Para eliminar todos os volumes definidos no arquivo prod-docker-compose.yml além dos contêineres, execute o comando down com o parâmetro -v:

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

Solução de problemas

Se o WADebug não puder ser usado ou a execução da ferramenta retornar erros, execute o seguinte comando para coletar registros de todos os contêineres:

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

Para coletar os registros de um serviço específico, anexe o nome do serviço (waweb ou wacore) ao comando docker-compose logs:

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

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