Easypanel

Pré-requisitos antes de começar:

VPS com Linux (Ubuntu ou Debian recomendado) e acesso root
Easypanel instalado no servidor (documentação oficial)
Domínio com registro A apontando para o IP do servidor — configure o DNS antes de iniciar o deploy. O Let’s Encrypt falha se o domínio não estiver propagado no momento da emissão do certificado.

O Easypanel é um painel de controle baseado em Docker Swarm com Traefik e SSL automático via Let’s Encrypt. A Evolution API possui um template oficial no Easypanel que provisiona automaticamente todos os serviços necessários.

O que será provisionado

Independente do método escolhido, a instalação cria três serviços dentro do seu projeto:

Serviço	Função	Porta interna
`evolution-api`	Aplicação principal	8080
`evolution-postgres`	Banco de dados	5432
`evolution-redis`	Cache e sessões	6379

Método A — Template 1-clique

O método mais rápido. O Easypanel provisiona os três serviços automaticamente a partir do template oficial. 1. Crie um projeto no Easypanel No painel, clique em ”+ Projeto”, escolha um nome (ex: evolution) e confirme. 2. Adicione o template Dentro do projeto, clique em ”+ Serviço” → “Templates”. Busque por Evolution API e selecione o template oficial. 3. Configure e crie Revise o nome dos serviços e clique em “Create”. O Easypanel irá provisionar os três serviços (api, postgres e redis) automaticamente. 4. Configure o domínio Acesse o serviço evolution-api → aba “Domains”. Adicione seu domínio e marque-o como primário (ícone de estrela). O certificado SSL será emitido automaticamente.

Certifique-se de que o registro A do domínio já está apontando para o IP do servidor antes de salvar. Sem isso, a emissão do SSL via Let’s Encrypt falhará.

5. Acesse o Evolution Manager Após o SSL ser emitido, acesse https://seu-dominio/manager e autentique-se com a API Key definida nas variáveis de ambiente do serviço.

Método B — Instalação manual

Recomendado quando você precisa de controle total sobre a configuração, usar um banco de dados ou Redis já existente, ou customizar os serviços antes do primeiro deploy. 1. Crie um projeto No painel, clique em ”+ Projeto” e escolha um nome (ex: evolution). Anote o nome exato — ele será usado nas strings de conexão. 2. Crie o serviço de banco de dados Dentro do projeto: ”+ Serviço” → “Postgres”. Anote a senha gerada — você vai precisar dela nas variáveis de ambiente. 3. Crie o serviço Redis ”+ Serviço” → “Redis”. Anote também a senha gerada. 4. Crie o serviço da aplicação ”+ Serviço” → “App” → selecione “Docker Image” como source. Use a imagem:

evoapicloud/evolution-api:v2.3.7

5. Configure o domínio com a porta correta Na aba “Domains” do serviço evolution-api, adicione seu domínio e defina a porta como 8080.

Informar a porta 8080 no mapeamento do domínio é obrigatório. Sem ela, o Traefik não consegue rotear as requisições para o serviço e ele ficará inacessível.

6. Configure as variáveis de ambiente Na aba “Environment”, preencha as variáveis conforme a seção abaixo. 7. Configure o volume persistente Na aba “Storage”, crie um volume apontando para /evolution/instances.

Não pule esta etapa. Sem o volume persistente, todas as sessões WhatsApp conectadas serão perdidas a cada restart ou redeploy do serviço.

8. Faça o deploy Clique em “Deploy”. Após a inicialização, configure o domínio (como no Método A, passo 4) e acesse https://seu-dominio/manager.

Variáveis de ambiente

Preencha as variáveis na aba “Environment” do serviço evolution-api. O exemplo abaixo considera que o projeto foi criado com o nome evolution. Se você usou outro nome, ajuste o hostname nas variáveis de banco de dados e Redis — o padrão é sempre NOME_DO_PROJETO_NOME_DO_SERVICO.

# === SERVIDOR ===
SERVER_URL=https://$(PRIMARY_DOMAIN)

# === INSTÂNCIAS ===
DEL_INSTANCE=false
DEL_TEMP_INSTANCES=false

# === PROVIDER ===
PROVIDER_ENABLED=false
PROVIDER_HOST=127.0.0.1
PROVIDER_PORT=5656
PROVIDER_PREFIX=evolution_v2

# === BANCO DE DADOS ===
DATABASE_ENABLED=true
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgres://postgres:SENHA_POSTGRES@NOME_DO_PROJETO_evolution-postgres:5432/evolution
DATABASE_CONNECTION_CLIENT_NAME=evolution_v2

# === CACHE REDIS ===
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://default:SENHA_REDIS@NOME_DO_PROJETO_evolution-redis:6379
CACHE_REDIS_PREFIX_KEY=evolution_v2
CACHE_REDIS_SAVE_INSTANCES=false
CACHE_LOCAL_ENABLED=false

# === S3 (opcional) ===
S3_ENABLED=false
S3_ACCESS_KEY=
S3_SECRET_KEY=

# === RABBITMQ (opcional) ===
RABBITMQ_ENABLED=false
RABBITMQ_URI=amqp://admin:admin@rabbitmq:5672/default

# === AUTENTICAÇÃO ===
AUTHENTICATION_API_KEY=CHAVE_256_BITS_AQUI

# === LOG ===
LOG_LEVEL=ERROR,WARN,INFO

Rede interna do Easypanel: serviços do mesmo projeto se comunicam usando o padrão NOME_DO_PROJETO_NOME_DO_SERVICO. Por exemplo, se o projeto se chama evolution, o host do Postgres será evolution_evolution-postgres. Esse é o erro mais comum em tutoriais antigos — não use localhost nem o IP do servidor.

A variável $(PRIMARY_DOMAIN) é preenchida automaticamente pelo Easypanel com o domínio marcado como primário no serviço. Não é necessário substituí-la manualmente.

Primeiro acesso ao Evolution Manager

O Evolution Manager está embutido na aplicação a partir da v2. Após o deploy:

Acesse https://seu-dominio/manager
Autentique-se com o valor definido em AUTHENTICATION_API_KEY
Clique em “New Instance” para criar sua primeira instância WhatsApp
Escaneie o QR Code com o WhatsApp do celular para conectar

Pontos críticos

#	Ponto	Impacto se ignorado
1	Volume persistente em `/evolution/instances`	Perda de todas as sessões WhatsApp a cada restart
2	DNS configurado antes do deploy	Falha na emissão do certificado SSL
3	Porta `8080` no mapeamento de domínio	Serviço inacessível via domínio
4	Padrão de rede interna `PROJETO_servico`	Falha na conexão com Postgres e Redis
5	`AUTHENTICATION_API_KEY` com 256 bits de entropia	Qualquer pessoa pode controlar as instâncias conectadas
6	Imagem `evoapicloud/evolution-api` (não `atendai/...`)	Deploy com versão desatualizada (v1.x)

Primeiros Passos

Configuração

Integrações

O que será provisionado

Método A — Template 1-clique

Método B — Instalação manual

Variáveis de ambiente

Primeiro acesso ao Evolution Manager

Pontos críticos

​O que será provisionado

​Método A — Template 1-clique

​Método B — Instalação manual

​Variáveis de ambiente

​Primeiro acesso ao Evolution Manager

​Pontos críticos

O que será provisionado

Método A — Template 1-clique

Método B — Instalação manual

Variáveis de ambiente

Primeiro acesso ao Evolution Manager

Pontos críticos