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
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:
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:
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443
sudo ufw enable
sudo ufw statusO 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:
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 versionOs 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:
mkdir -p ~/evolution && cd ~/evolutionGere a chave global da API. Não reutilize o exemplo que vem no .env.example do repositório:
openssl rand -hex 16Crie 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:
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-senhaA 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.
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-netO Caddy emite e renova o certificado. Troque o domínio e o e-mail:
api.example.com {
reverse_proxy evolution_api:8080
tls [email protected]
}Suba a stack e acompanhe a API até ela responder:
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f apiO 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:
curl -fsS https://api.example.comA 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:
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 apiO 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:
sudo docker compose pull api
sudo docker compose up -d api
sudo docker compose logs -f apiLeia 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.