Evolution API: Instale e Gerencie em seu VPS (Do Zero à Produção)

Evolution API: Instale e Gerencie em Seu Próprio Servidor VPS

A Evolution API é uma solução robusta para integrar o WhatsApp em suas aplicações, permitindo automação, chatbots e gerenciamento de mensagens via API. Se você valoriza controle total, segurança e personalização, rodar a Evolution API em seu próprio VPS (Virtual Private Server) é a escolha estratégica. Este guia prático foca na implantação e gerenciamento da Evolution API em um ambiente auto-hospedado, assumindo que você já decidiu que o controle total é o caminho. Vamos direto ao ponto: a instalação em um servidor Ubuntu, os requisitos essenciais e como colocá-la para funcionar em minutos.

Veja a infraestrutura: VPS para n8n + Evolution API para colocar este projeto no ar.

Para rodar a Evolution API em produção de forma eficiente, recomendamos um servidor com no mínimo 4GB de RAM e 4 vCPUs. Um plano como o VPS Brasil Básico da Host You Secure, com 4GB de RAM e 4 vCPUs por R$ 99/mês, é um excelente ponto de partida para testes e até mesmo para operações de menor escala. Para ambientes com maior volume de mensagens e necessidade de alta disponibilidade, considere planos com mais recursos.

Requisitos Essenciais para sua Evolution API no VPS

Antes de iniciar a implantação, é crucial entender os requisitos de infraestrutura para garantir que sua Evolution API opere de maneira estável e performática. Um ambiente mal configurado pode levar a gargalos, falhas na entrega de mensagens e experiências ruins para seus usuários.

Recursos Mínimos de Servidor

Para uma instalação básica e funcional da Evolution API, incluindo o banco de dados e o proxy reverso, recomendo:

• Sistema Operacional: Ubuntu Server 20.04 LTS ou superior.
• RAM: Mínimo de 4GB. Para produção com tráfego moderado, 4GB é mais recomendado para garantir fluidez com o banco de dados e o serviço principal.
• vCPUs: Mínimo de 4 vCPUs.
• Armazenamento: 20GB de espaço livre. Isso deve ser suficiente para os containers, logs e banco de dados, mas monitore o crescimento do banco de dados.
• Docker e Docker Compose: Essenciais para a orquestração dos containers.

Recursos Recomendados para Produção

Para garantir alta disponibilidade e performance, especialmente se você planeja lidar com um grande volume de mensagens ou múltiplos números, considere:

• RAM: 4GB ou mais. Isso acomoda confortavelmente a Evolution API, o banco de dados (PostgreSQL é uma escolha comum e robusta) e o proxy reverso (Nginx ou Traefik).
• vCPUs: 4 vCPUs para melhor paralelismo e resposta rápida.
• Armazenamento: 50GB SSD. SSDs oferecem velocidade crucial para o banco de dados e operações de I/O.
• Conexão de Rede: Estável e com boa latência para os servidores do WhatsApp.

Passo a Passo: Instalando a Evolution API com Docker e Docker Compose

A forma mais recomendada e eficiente de implantar a Evolution API é utilizando Docker e Docker Compose. Isso garante que todas as dependências sejam gerenciadas em containers isolados, facilitando a instalação, atualização e manutenção. Este tutorial assume que você já tem um VPS com Ubuntu e acesso root ou sudo.

1. Instalação do Docker e Docker Compose

Primeiro, atualize seus pacotes e instale o Docker:

sudo apt update && sudo apt upgrade -y
sudo apt install docker.io docker-compose -y

# Verifique a instalação
docker --version
docker-compose --version

Adicione seu usuário ao grupo docker para evitar usar sudo a cada comando:

sudo usermod -aG docker $USER
newgrp docker

2. Preparando o Ambiente e o Arquivo Docker Compose

Crie um diretório para a Evolution API e navegue até ele:

mkdir evolution-api
cd evolution-api

Agora, crie o arquivo docker-compose.yml. Este arquivo define os serviços necessários: a Evolution API, um banco de dados PostgreSQL e o serviço de cache Redis. É crucial configurar corretamente as variáveis de ambiente, especialmente as credenciais do banco de dados e as chaves secretas.

version: '3.8'

services:
  evolution-api:
    image: evolutionapi/evolutionapi:latest
    container_name: evolution-api
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - DB_HOST=db
      - DB_PORT=5432
      - DB_USER=evolution
      - DB_PASSWORD=evolution_password
      - DB_NAME=evolution
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - APP_SECRET=YOUR_APP_SECRET_VERY_SECRET
      - JWT_SECRET=YOUR_JWT_SECRET_VERY_SECRET
      - CHATWOOT_URL= # Se usar chatwoot
      - CHATWOOT_TOKEN= # Se usar chatwoot
      - MEILISEARCH_URL= # Se usar meilisearch
      - MEILISEARCH_KEY= # Se usar meilisearch
    depends_on:
      - db
      - redis
    networks:
      - evolution-network

  db:
    image: postgres:13
    container_name: evolution-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=evolution
      - POSTGRES_PASSWORD=evolution_password
      - POSTGRES_DB=evolution
    volumes:
      - evolution-db-data:/var/lib/postgresql/data
    networks:
      - evolution-network

  redis:
    image: redis:latest
    container_name: evolution-redis
    restart: unless-stopped
    volumes:
      - evolution-redis-data:/data
    networks:
      - evolution-network

volumes:
  evolution-db-data:
  evolution-redis-data:

networks:
  evolution-network:
    driver: bridge

Importante: Altere evolution_password, YOUR_APP_SECRET_VERY_SECRET e YOUR_JWT_SECRET_VERY_SECRET para senhas fortes e únicas. Se você já possui um banco de dados ou Redis configurado e quer que a Evolution API use, ajuste os parâmetros DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME, REDIS_HOST e REDIS_PORT de acordo. A configuração CHOOSE_MEILISEARCH_CONNECTION=true e MEILISEARCH_URL/MEILISEARCH_KEY é para integrações com Meilisearch, caso decida utilizá-lo para buscas mais avançadas.

3. Iniciando os Containers

Com o arquivo docker-compose.yml pronto, inicie os serviços:

docker-compose up -d

O comando -d inicia os containers em modo detached (em segundo plano). Você pode verificar o status dos containers com:

docker ps

Aguarde alguns minutos para que os containers iniciem completamente e as migrações do banco de dados sejam aplicadas. O tempo de inicialização pode variar dependendo dos recursos do seu VPS.

4. Configurando o Proxy Reverso (Nginx)

Para acessar a Evolution API de forma segura e externa, é altamente recomendável configurar um proxy reverso. O Nginx é uma escolha popular e eficiente.

Instale o Nginx:

sudo apt install nginx -y

Crie um novo arquivo de configuração para a Evolution API:

sudo nano /etc/nginx/sites-available/evolution-api

Adicione o seguinte conteúdo, substituindo seu_dominio.com pelo seu domínio ou endereço IP público:

server {
    listen 80;
    server_name seu_dominio.com;

    location / {
        proxy_pass http://localhost:5000; # Porta onde a Evolution API está rodando
        proxy_set_header Host $host;
        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;
    }

    # Opcional: Configuração para WebSockets, se necessário para alguma funcionalidade
    location /socket.io/ {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Habilite o site e reinicie o Nginx:

sudo ln -s /etc/nginx/sites-available/evolution-api /etc/nginx/sites-enabled/
sudo nginx -t # Teste a configuração
sudo systemctl restart nginx

Se desejar usar HTTPS, você precisará obter um certificado SSL (por exemplo, com Let's Encrypt) e configurar o Nginx para usá-lo. Para um guia detalhado sobre como configurar o Nginx com Let's Encrypt, você pode consultar este guia sobre deploy com Docker, que aborda a configuração do proxy reverso.

Gerenciamento e Monitoramento da Evolution API

Após a instalação, o gerenciamento contínuo é fundamental para a estabilidade e segurança da sua instância da Evolution API.

Monitoramento de Logs e Performance

Utilize os comandos do Docker para monitorar os logs e o estado dos seus containers:

• docker logs evolution-api: Visualiza os logs da Evolution API.
• docker logs db: Visualiza os logs do banco de dados PostgreSQL.
• docker stats: Monitora o uso de CPU e RAM dos containers em tempo real.

É aconselhável implementar um sistema de monitoramento mais robusto, como o Uptime Kuma ou Prometheus com Grafana, para ter alertas proativos sobre o status dos seus serviços. Hospedar ferramentas como o Uptime Kuma em seu próprio VPS é uma prática recomendada para monitorar serviços críticos como a Evolution API. Você pode encontrar um guia prático sobre como hospedar Uptime Kuma em VPS em nosso blog.

Atualizações da Evolution API

Para atualizar a Evolution API para a versão mais recente, você geralmente seguirá estes passos:

1. Pare os containers: docker-compose down
2. Baixe a nova imagem: docker-compose pull evolution-api
3. Inicie novamente: docker-compose up -d

Verifique sempre a documentação oficial da Evolution API para procedimentos de atualização específicos e potenciais alterações nas variáveis de ambiente ou estrutura do banco de dados.

Erros Comuns e Soluções

Ao implantar a Evolution API, alguns problemas podem surgir. Estar ciente deles pode economizar tempo e frustração.

Problemas de Conexão com o Banco de Dados

Se a Evolution API não inicia e os logs indicam falha na conexão com o banco de dados:

• Verifique se o container do banco de dados (db) está rodando.
• Confira se as variáveis de ambiente DB_HOST, DB_PORT, DB_USER, DB_PASSWORD e DB_NAME no seu docker-compose.yml estão corretas e correspondem às configurações do container db.
• Certifique-se de que os containers estão na mesma rede Docker (evolution-network no exemplo).

Falha ao Iniciar a Aplicação

Se o container da Evolution API falha ao iniciar:

• Analise os logs detalhadamente (docker logs evolution-api) para identificar a causa raiz. Erros comuns incluem senhas incorretas para o banco de dados ou chaves secretas ausentes/inválidas.
• Verifique os requisitos de RAM do seu VPS. Se o servidor estiver com pouca memória, o container pode não iniciar.

Acesso Externo Negado (Proxy Reverso)

Se você não consegue acessar a Evolution API pelo seu domínio ou IP:

• Confirme se o Nginx está rodando e sem erros (sudo systemctl status nginx).
• Verifique se a configuração do Nginx aponta para o IP/porta corretos (localhost:5000 no exemplo).
• Assegure-se de que as portas 80 (e 443 se usar HTTPS) estão abertas no firewall do seu VPS. Use sudo ufw status para verificar.

Comparativo de Requisitos: Evolution API

Perguntas Relacionadas

Qual a versão recomendada do Docker para Evolution API?

A Evolution API geralmente funciona bem com versões recentes do Docker e Docker Compose. Recomendamos sempre usar as versões mais estáveis e atualizadas disponíveis para seu sistema operacional, garantindo compatibilidade e segurança.

Posso rodar Evolution API em um servidor compartilhado?

Não é recomendado. A Evolution API requer um ambiente dedicado como um VPS para garantir o isolamento, performance e controle necessários. Servidores compartilhados não oferecem os recursos nem a configuração adequada para rodar aplicações via Docker.

Como conectar múltiplos números de WhatsApp na Evolution API?

A Evolution API foi projetada para gerenciar múltiplos números. Você precisará configurar instâncias separadas para cada número ou, dependendo da arquitetura, configurar múltiplos endpoints ou instâncias do serviço, cada um associado a um número diferente.

É necessário um número de telefone dedicado para a Evolution API?

Sim, é necessário um número de telefone (preferencialmente um chip SIM ou um número virtual VoIP compatível) que possa receber SMS ou chamadas para a verificação inicial e para operar o WhatsApp Business API ou o WhatsApp via `whatsapp-web.js`.

Conclusão e Próximos Passos

Implantar e gerenciar a Evolution API em seu próprio VPS é uma decisão poderosa para quem busca controle e flexibilidade na automação do WhatsApp. Com os requisitos de hardware adequados e seguindo os passos de instalação com Docker e Docker Compose, você terá sua instância rodando em pouco tempo. Lembre-se de configurar um proxy reverso para segurança e monitorar seus serviços continuamente.

A Host You Secure oferece a infraestrutura ideal para suas necessidades. Para iniciar seu projeto de automação com a Evolution API, recomendamos o plano VPS Brasil Básico. Testamos cada comando deste artigo em uma VPS Brasil Básico, garantindo que ela é perfeitamente capaz de hospedar sua Evolution API com 4GB de RAM e 4 vCPUs por apenas R$ 99/mês. Comece hoje mesmo a construir sua solução de automação!

Adquira seu VPS Brasil Básico Agora