Ir para o conteúdo

Tutorial

Como instalar a Evolution API em uma VPS (passo a passo com Docker)

Este guia sobe a Evolution API numa VPS Ubuntu 24.04: a API, o PostgreSQL 15, o Redis e o Caddy na frente, com HTTPS. O Compose parte do arquivo oficial e tira a rede externa do Dokploy, que só existe nesse painel e faria o docker compose up falhar numa VPS comum.

Neste artigo
  1. O que você vai precisar
  2. Preparar o servidor
  3. Instalar o Docker
  4. Configurar a Evolution API
  5. Criar a primeira instância
  6. Atualizar e fazer backup
  7. Próximo passo

O que você vai precisar

  • Uma VPS com Ubuntu 24.04 de 64 bits e SSH com um usuário que tenha sudo.
  • Um domínio em que você consiga criar um registro DNS. Os exemplos usam api.example.com.
  • Um e-mail para a conta ACME do certificado.

A documentação da Evolution API pede PostgreSQL ou MySQL e recomenda o Redis. Este guia usa os dois. Trate 2 vCPU e 4 GB de RAM como piso para a API, o banco e o cache juntos. Com 4 vCPU e 8 GB sobra espaço para mais instâncias e para o banco crescer.

Se você só quer experimentar, a Nuvits também entrega a VPS com o Docker já instalado na contratação. A Evolution API em si continua por sua conta: o passo a passo abaixo é o caminho com domínio e HTTPS.

Preparar o servidor

Se a VPS chega com acesso de root, crie um usuário com sudo e copie a sua chave SSH:

bash
adduser deploy
usermod -aG sudo deploy
install -d -m 700 -o deploy -g deploy /home/deploy/.ssh
install -m 600 -o deploy -g deploy ~/.ssh/authorized_keys /home/deploy/.ssh/

Abra outra sessão como deploy e confira o login antes de fechar a de root. Depois libere SSH, HTTP e HTTPS:

bash
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443
sudo ufw enable
sudo ufw status

O ufw enable pede confirmação porque pode derrubar o SSH. Com a regra da porta 22 já criada, responda y.

Instalar o Docker

Na Nuvits, dá para pedir a VPS com o Docker já instalado. Nesse caso, pule para o docker compose version no fim desta seção.

O caminho que a documentação do Docker indica para servidores é o repositório apt oficial:

bash
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo docker run hello-world
docker compose version

Os comandos usam sudo docker. O grupo docker dispensa o sudo, mas a documentação do Docker avisa que ele equivale a root.

Configurar a Evolution API

Crie a pasta do projeto. O nome dela vira prefixo dos volumes:

bash
mkdir -p ~/evolution && cd ~/evolution

Gere a chave global da API. Não reutilize o exemplo que vem no .env.example do repositório:

bash
openssl rand -hex 16

Crie o .env com a chave, o endereço público e o banco. Os nomes SERVER_URL, AUTHENTICATION_API_KEY, DATABASE_PROVIDER, DATABASE_CONNECTION_URI, CACHE_REDIS_ENABLED e CACHE_REDIS_URI estão no .env.example atual do repositório. POSTGRES_* alimenta a imagem oficial do PostgreSQL:

.env
SERVER_URL=https://api.example.com
AUTHENTICATION_API_KEY=cole-aqui-a-chave

DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://evolution:cole-a-senha@evolution-postgres:5432/evolution_db?schema=evolution_api
DATABASE_CONNECTION_CLIENT_NAME=evolution

CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://evolution-redis:6379/6
CACHE_REDIS_PREFIX_KEY=evolution

POSTGRES_DATABASE=evolution_db
POSTGRES_USERNAME=evolution
POSTGRES_PASSWORD=cole-a-senha

A senha do DATABASE_CONNECTION_URI e a de POSTGRES_PASSWORD precisam ser a mesma. Se a senha tiver @, :, / ou #, troque esses caracteres pelo código percentual na URI, senão o cliente lê o endereço errado.

Aponte api.example.com para o IPv4 da VPS antes de subir o Caddy. Sem isso o certificado não sai.

Compose

O arquivo abaixo usa as mesmas imagens do docker-compose.yaml oficial: evoapicloud/evolution-api:latest, postgres:15 e redis:latest. A rede dokploy-network ficou de fora, porque ela é externa e não existe numa VPS recém-criada. A tag latest é a que o arquivo oficial usa; para travar uma versão, troque pela tag publicada no repositório antes de subir.

docker-compose.yml
services:
  api:
    container_name: evolution_api
    image: evoapicloud/evolution-api:latest
    restart: always
    depends_on:
      - redis
      - evolution-postgres
    ports:
      - "127.0.0.1:8080:8080"
    env_file:
      - .env
    volumes:
      - evolution_instances:/evolution/instances
    networks:
      - evolution-net

  redis:
    container_name: evolution_redis
    image: redis:latest
    restart: always
    command: redis-server --port 6379 --appendonly yes
    volumes:
      - evolution_redis:/data
    networks:
      evolution-net:
        aliases:
          - evolution-redis

  evolution-postgres:
    container_name: evolution_postgres
    image: postgres:15
    restart: always
    environment:
      POSTGRES_DB: ${POSTGRES_DATABASE}
      POSTGRES_USER: ${POSTGRES_USERNAME}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    command: ["postgres", "-c", "max_connections=1000"]
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - evolution-net

  caddy:
    image: caddy:2.10
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - evolution-net

volumes:
  evolution_instances:
  evolution_redis:
  postgres_data:
  caddy_data:
  caddy_config:

networks:
  evolution-net:
    name: evolution-net

O Caddy emite e renova o certificado. Troque o domínio e o e-mail:

Caddyfile
api.example.com {
	reverse_proxy evolution_api:8080
	tls [email protected]
}

Suba a stack e acompanhe a API até ela responder:

bash
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f api

O contêiner da API aplica as migrações do Prisma na subida, conforme o DATABASE_PROVIDER. Se o certificado não sair, confira o DNS e as portas 80 e 443 e rode sudo docker compose restart caddy.

De fora da VPS:

bash
curl -fsS https://api.example.com

A resposta não precisa ser uma página HTML. O que importa é o TLS válido e a API no ar. As chamadas usam o cabeçalho apikey com o valor de AUTHENTICATION_API_KEY, como a documentação da API descreve.

Criar a primeira instância

A Evolution API conecta pelo WhatsApp Web, com a biblioteca Baileys, ou pela API oficial da Meta. A própria documentação avisa que a conexão pelo WhatsApp Web pode ter limitações em relação à API oficial.

Com a API no ar, crie a instância pelo endpoint documentado (POST /instance/create) e leia o QR Code em GET /instance/connect/{instancia}. Abra o WhatsApp no celular, em Aparelhos conectados, e escaneie o código. O SERVER_URL precisa ser o endereço público com https, senão os webhooks saem apontando para localhost.

O repositório também publica a imagem evoapicloud/evolution-manager, um painel web. Ela não entra neste Compose: publique só em 127.0.0.1 e ponha outro site no Caddy se quiser usá-la. Sem isso, a porta 3000 do exemplo oficial fica aberta na internet.

Atualizar e fazer backup

Pare a API, grave o banco e a pasta de instâncias, e copie os dois para fora da VPS:

bash
cd ~/evolution
sudo docker compose stop api
sudo docker compose exec -T evolution-postgres pg_dump -U evolution evolution_db > evolution-$(date +%F).sql
sudo docker run --rm -v evolution_evolution_instances:/from -v "$PWD":/backup ubuntu:24.04 tar czf /backup/evolution-instances-$(date +%F).tar.gz -C /from .
sudo docker compose start api

O nome do volume ganha o prefixo da pasta do projeto (evolution_). Confira com sudo docker volume ls se o tar reclamar que o volume não existe. Copie o .sql, o arquivo e o .env para a sua máquina. Uma cópia que fica só no disco da VPS se perde junto com ela.

Para atualizar, troque a tag da imagem se você tiver travado uma versão, ou rode o pull da latest, e recrie só a API:

bash
sudo docker compose pull api
sudo docker compose up -d api
sudo docker compose logs -f api

Leia as notas da versão no repositório antes. O pull da latest não avisa quando uma mudança exige um passo manual no banco.

Próximo passo

A VPS, o domínio e o certificado ficam com você. Se ainda não tem o servidor, veja os planos em VPS para Evolution API.