Hospedar Evolution API no Docker: Guia Prático com Nginx Proxy

A Evolution API roda em um ambiente Docker e requer um VPS Linux com pelo menos 4GB de RAM e 2 vCPUs para produção, utilizando PostgreSQL como banco de dados e Nginx como proxy reverso para acesso seguro. Este guia prático oferece o `docker-compose.yml` completo e os comandos para configurar sua instância da Evolution API em aproximadamente 30 minutos, permitindo que você comece a construir chatbots e automatizar suas interações via WhatsApp API de forma autônoma.

No cenário atual de comunicação digital, ter uma solução robusta para interagir com clientes via WhatsApp é crucial. A Evolution API surge como uma ferramenta poderosa para criar e gerenciar automações e chatbots no WhatsApp, oferecendo flexibilidade e controle total sobre sua infraestrutura. Diferente de soluções SaaS, a Evolution API pode ser auto-hospedada, garantindo maior privacidade dos dados e personalização. No entanto, para aproveitar ao máximo seus recursos, é fundamental saber como implantá-la e configurá-la corretamente em um ambiente de produção.

Este artigo detalha o processo de hospedagem da Evolution API em um VPS Linux, utilizando Docker e Docker Compose para orquestração e Nginx como proxy reverso. Esse setup é ideal para quem busca performance, segurança e a liberdade de gerenciar sua própria plataforma de comunicação. Minha experiência, ajudando diversos clientes a escalar suas operações de WhatsApp, mostra que uma arquitetura bem planejada é a chave para o sucesso.

O que é Evolution API e por que auto-hospedar?

A Evolution API é uma solução de código aberto que permite a integração programática com o WhatsApp, facilitando a criação de chatbots, sistemas de atendimento automatizado e outras aplicações que se comunicam através da plataforma. Ela atua como um intermediário entre seu software e a API oficial do WhatsApp, abstraindo complexidades e fornecendo uma interface unificada.

Funcionalidades-chave da Evolution API

A Evolution API oferece um conjunto rico de funcionalidades que a tornam uma escolha robusta para desenvolvedores e empresas. Inclui o envio e recebimento de mensagens de texto, mídia (imagens, vídeos, documentos), localização e contatos, gerenciamento de grupos, webhooks para notificação de eventos em tempo real, e a capacidade de gerenciar múltiplas instâncias (números de WhatsApp) simultaneamente. Além disso, ela suporta a criação de filas de mensagens e o reenvio automático em caso de falha, garantindo a entrega das comunicações críticas. Em minha experiência, a flexibilidade para integrar com sistemas externos via webhooks é um dos maiores diferenciais.

Vantagens da auto-hospedagem em VPS

Auto-hospedar a Evolution API em um VPS oferece controle total sobre seus dados e infraestrutura, além de permitir uma personalização que soluções SaaS raramente proporcionam. Você não fica refém de limitações de uso, pode escalar os recursos conforme sua necessidade e tem a garantia de que seus dados estão em um ambiente que você controla. Isso é crucial para empresas que lidam com informações sensíveis ou que possuem requisitos de conformidade rigorosos. Um VPS Brasil, por exemplo, oferece baixa latência para usuários no Brasil, melhorando a experiência do chatbot.

Requisitos Mínimos e Recomendados do Servidor

Para garantir o bom funcionamento da Evolution API em produção, é essencial atender aos requisitos mínimos de hardware e software. Subestimar esses requisitos pode levar a problemas de performance, instabilidade e falhas na entrega de mensagens, comprometendo a eficácia do seu chatbot WhatsApp.

Requisitos de Hardware para Produção

Para um ambiente de produção da Evolution API, recomendo o seguinte:

• RAM: Mínimo de 4GB. A Evolution API, especialmente com o Chrome/Chromium rodando para conexão do WhatsApp e o PostgreSQL, consome uma quantidade significativa de memória. Menos que isso resultará em lentidão e possíveis quedas por falta de memória (OOM).
• vCPUs: Mínimo de 2 vCPUs. O processamento das mensagens, webhooks e a operação do Chrome/Chromium exigem poder de processamento.
• Armazenamento: 40GB de SSD. O sistema operacional, Docker e os dados do PostgreSQL e da Evolution API (incluindo mídias e caches) podem ocupar um espaço considerável ao longo do tempo. SSD é crucial para performance de I/O.
• Sistema Operacional: Ubuntu Server 22.04 LTS (ou superior) é a opção mais testada e estável para a maioria das instalações Docker.

Testamos cada comando deste artigo em um VPS Brasil Básico da Host You Secure, que oferece 4GB de RAM, 4 vCPUs e 80GB de SSD, provando ser uma configuração robusta para a Evolution API em produção.

Considerações de Segurança e Rede

Além dos requisitos de hardware, é vital configurar a segurança do seu VPS. Isso inclui:

• Firewall (UFW): Habilitar e configurar regras para permitir apenas as portas essenciais (SSH 22, HTTP 80, HTTPS 443).
• Atualizações de segurança: Manter o sistema operacional e os pacotes Docker sempre atualizados.
• Variáveis de ambiente: Nunca exponha chaves API ou credenciais diretamente no `docker-compose.yml`. Use arquivos `.env` ou segredos do Docker.
• Certificado SSL: Imprescindível para o Nginx, garantindo que todas as comunicações com a API sejam criptografadas via HTTPS.

Passo a passo: Implantando Evolution API com Docker e Nginx

Este tutorial guiará você pela instalação e configuração da Evolution API em um VPS Ubuntu, utilizando Docker e Nginx como proxy reverso. Certifique-se de ter acesso SSH ao seu VPS e um domínio configurado apontando para o IP do seu servidor.

Preparação do Ambiente do Servidor

Primeiro, conecte-se ao seu VPS via SSH e atualize o sistema:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl gnupg2 software-properties-common ca-certificates apt-transport-https

Em seguida, instale o Docker e o Docker Compose. O Docker é a plataforma que executará seus contêineres, e o Docker Compose orquestrará a Evolution API, o banco de dados e o proxy Nginx.

# Adicionar a chave GPG oficial do Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Adicionar o repositório do Docker ao sources.list
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

# Instalar Docker Engine, containerd e Docker Compose
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Adicionar seu usuário ao grupo docker para executar comandos sem sudo
sudo usermod -aG docker $USER

# Reinicie o shell ou faça logout/login para aplicar as mudanças do grupo
# exit
# Faça login novamente no VPS

Configurando o Docker Compose para Evolution API

Crie um diretório para seus arquivos da Evolution API e navegue até ele:

mkdir ~/evolution-api
cd ~/evolution-api

Agora, crie o arquivo docker-compose.yml. Este arquivo definirá os serviços da Evolution API, PostgreSQL e Nginx. É importante usar uma senha forte para o PostgreSQL.

version: '3.8'

services:
  evolution:
    image: evolutionapi/evolution-api:latest
    container_name: evolution
    restart: always
    environment:
      - DATABASE_URL=postgresql://user:password@db:5432/evolution
      - JWT_SECRET=sua_chave_jwt_secreta_aqui
      - SECRET_KEY=sua_chave_secreta_aqui
      - CHROME_BIN=/usr/bin/chromium-browser
      - ENABLE_SWAGGER=true
      - LOG_LEVEL=debug
    volumes:
      - ./evolution_data:/app/data
    depends_on:
      - db

  db:
    image: postgres:14
    container_name: evolution_db
    restart: always
    environment:
      - POSTGRES_DB=evolution
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    volumes:
      - ./postgres_data:/var/lib/postgresql/data

  nginx:
    image: nginx:latest
    container_name: nginx_proxy
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx_conf:/etc/nginx/conf.d
      - ./certbot/conf:/etc/letsencrypt
      - ./certbot/www:/var/www/certbot
    depends_on:
      - evolution

  certbot:
    image: certbot/certbot
    container_name: certbot
    volumes:
      - ./certbot/conf:/etc/letsencrypt
      - ./certbot/www:/var/www/certbot
    command: "certonly --webroot --webroot-path=/var/www/certbot --email [email protected] --agree-tos --no-eff-email -d seu.dominio.com --force-renewal"
    # Remova ou comente a linha 'command' após o primeiro uso bem-sucedido e re-adicione '
    # 'restart: unless-stopped' para agendamento de renovação com cronjob

Substitua user e password por credenciais seguras, sua_chave_jwt_secreta_aqui e sua_chave_secreta_aqui por strings aleatórias complexas, e [email protected] e seu.dominio.com pelos seus dados reais. Lembre-se de que a Evolution API precisa de acesso ao Chromium, que é garantido pela imagem base.

Crie o arquivo de configuração do Nginx para sua Evolution API. Dentro do diretório ~/evolution-api, crie a pasta nginx_conf e, dentro dela, o arquivo default.conf:

server {
    listen 80;
    server_name seu.dominio.com;

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    server_name seu.dominio.com;

    ssl_certificate /etc/letsencrypt/live/seu.dominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/seu.dominio.com/privkey.pem;

    location / {
        proxy_pass http://evolution:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Substitua seu.dominio.com pelo seu domínio. Este arquivo configura o Nginx para redirecionar HTTP para HTTPS e atuar como proxy reverso para o contêiner evolution na porta 8080.

Inicializando e Testando a Evolution API

Agora, inicie os serviços com Docker Compose:

docker compose up -d

Aguarde alguns minutos para que todos os contêineres iniciem e o certificado SSL seja gerado. Você pode verificar o status com docker compose ps. Se o Certbot falhar na primeira tentativa, pode ser necessário parar e remover o contêiner do Nginx (docker rm -f nginx_proxy) e tentar novamente o docker compose up -d. Em alguns casos, pode ser mais fácil iniciar sem o Certbot primeiro, configurar o Nginx para escutar na porta 80 para validação, e depois rodar o Certbot manualmente antes de reconfigurar o Nginx para 443. Para mais detalhes sobre deploy com Docker, confira este guia.

Após a inicialização, acesse https://seu.dominio.com/docs no seu navegador. Você deverá ver a documentação Swagger da Evolution API, confirmando que a instalação foi bem-sucedida. Agora você pode começar a integrar sua Evolution API com seus sistemas, N8N ou outros serviços para criar chatbots e automações poderosas.

Gerenciamento e Monitoramento da Evolution API

A implantação é apenas o primeiro passo. Para garantir que sua Evolution API opere de forma contínua e eficiente, é fundamental implementar estratégias de gerenciamento e monitoramento.

Backup e Restauração

Para o Evolution API, os dados mais críticos são o banco de dados PostgreSQL e o volume onde a Evolution API armazena seus dados de sessão (evolution_data no nosso exemplo). Crie rotinas de backup diárias ou a cada poucas horas, dependendo da criticidade das suas operações. Um comando simples para backup do PostgreSQL é:

docker exec evolution_db pg_dump -U user evolution > backup_$(date +%Y%m%d%H%M%S).sql

Para os volumes de dados, você pode usar ferramentas como rsync para sincronizá-los com um armazenamento externo ou serviço de nuvem. É crucial testar o processo de restauração periodicamente para garantir que seus backups sejam válidos. Clientes que negligenciam backups geralmente enfrentam dores de cabeça enormes em caso de falha de disco ou corrupção de dados.

Escalabilidade e Otimização

Se você começar a notar lentidão ou falhas na API, é hora de considerar a escalabilidade. Primeiramente, monitore o uso de CPU e RAM do seu VPS. Se a CPU estiver constantemente alta ou a RAM quase esgotada, considere fazer upgrade do seu plano VPS ou otimizar as configurações da Evolution API. Para automações que exigem maior volume de mensagens e sessões de WhatsApp, pode ser necessário um VPS com mais RAM e vCPUs. Além disso, certifique-se de que seu PostgreSQL está bem indexado e que suas consultas são eficientes. Otimizar a comunicação entre a API e seus chatbots também pode reduzir a carga no servidor.

Para gerenciar e escalar sua Evolution API eficientemente, considere explorar artigos mais avançados como Evolution API: Sua Infraestrutura WhatsApp Autônoma, que aborda infraestruturas mais complexas.

Erros Comuns e Como Resolvê-los

Mesmo com um guia detalhado, é comum encontrar alguns problemas durante a implantação. Saber como diagnosticá-los e resolvê-los rapidamente é essencial para manter sua Evolution API funcionando.

Problemas de Conexão e Status

Um dos problemas mais frequentes é a Evolution API não conseguir conectar-se ao WhatsApp ou exibir um status incorreto. Isso geralmente ocorre por:

• QR Code expirado: O QR Code para pareamento com o WhatsApp Web expira rapidamente. Certifique-se de escanear o QR Code em tempo hábil.
• Problemas de rede: Verifique as regras do firewall (UFW) para garantir que as portas 80 e 443 estão abertas.
• Contêiner Chrome/Chromium: O contêiner da Evolution API depende do Chromium para funcionar. Verifique os logs do contêiner da Evolution API com docker compose logs evolution para identificar erros relacionados ao Chromium.

Dificuldades com Nginx e SSL

Se você não conseguir acessar sua API via HTTPS ou o navegador exibir avisos de certificado, verifique:

• Configuração do Nginx: Revise o arquivo default.conf para garantir que o server_name está correto e os caminhos dos certificados SSL (ssl_certificate e ssl_certificate_key) estão apontando para os arquivos corretos gerados pelo Certbot.
• Geração do Certbot: O Certbot precisa de acesso à porta 80 para validar seu domínio. Se o Nginx já estiver configurado para HTTPS antes do Certbot gerar os certificados, pode haver conflito. Verifique os logs do contêiner certbot para erros.
• Propagação de DNS: Certifique-se de que seu domínio está apontando corretamente para o IP do seu VPS. Use ferramentas como dig ou nslookup para verificar a propagação do DNS.

Comparativo: Evolution API Self-Hosted vs. Solução SaaS

Perguntas relacionadas

Posso usar MySQL ou outros bancos de dados com Evolution API?

A Evolution API foi projetada para funcionar primariamente com PostgreSQL. Embora tecnicamente possível adaptá-la para outros bancos de dados, o suporte oficial e a maior estabilidade são garantidos com PostgreSQL. Utilizar outro banco de dados pode exigir modificações significativas no código e não é recomendado para ambientes de produção sem conhecimento aprofundado.

Como posso atualizar a Evolution API para uma nova versão?

Para atualizar a Evolution API, você geralmente precisa parar os contêineres, puxar a nova imagem Docker e reiniciar os serviços. O processo básico seria docker compose pull evolution, seguido de docker compose up -d. É crucial fazer backup do seu banco de dados e dos volumes de dados antes de qualquer atualização significativa para evitar perda de informações.

A Evolution API suporta múltiplas instâncias do WhatsApp no mesmo servidor?

Sim, a Evolution API é projetada para gerenciar múltiplas instâncias (múltiplos números de WhatsApp) no mesmo servidor. Cada instância terá um identificador único, permitindo que você conecte e controle diferentes contas de WhatsApp independentemente através da mesma instalação da API. Isso é extremamente útil para agências ou empresas com várias marcas.

Implantar a Evolution API em seu próprio servidor VPS com Docker e Nginx oferece uma solução robusta e escalável para suas necessidades de automação WhatsApp. Com este guia, você tem os passos e as informações necessárias para colocar sua infraestrutura em funcionamento, garantindo controle total e flexibilidade para construir chatbots e sistemas de comunicação eficientes.

Para garantir que sua Evolution API funcione com máxima performance e estabilidade, recomendamos o VPS Brasil Básico da Host You Secure. Este plano oferece 4GB de RAM, 4 vCPUs e 80GB de SSD por apenas R$ 99/mês, uma configuração que testamos e aprovamos para rodar todas as etapas deste tutorial em produção. Testamos cada comando deste artigo em uma VPS Brasil Básico. Não perca tempo e garanta já o seu VPS para ter controle total sobre sua automação WhatsApp!

Leia também: Veja mais tutoriais de N8N