> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolutionfoundation.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Easypanel

> Instale a Evolution API no Easypanel usando o template oficial 1-clique ou configurando os serviços manualmente.

<Note>
  **Pré-requisitos antes de começar:**

  * VPS com Linux (Ubuntu ou Debian recomendado) e acesso root
  * Easypanel instalado no servidor ([documentação oficial](https://easypanel.io/docs))
  * 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.
</Note>

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.

<Warning>
  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á.
</Warning>

**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`**.

<Warning>
  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.
</Warning>

**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`.

<Warning>
  **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.
</Warning>

**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`.

```dotenv theme={null}
# === 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
```

<Note>
  **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.
</Note>

<Note>
  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.
</Note>

***

## Primeiro acesso ao Evolution Manager

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

1. Acesse `https://seu-dominio/manager`
2. Autentique-se com o valor definido em `AUTHENTICATION_API_KEY`
3. Clique em **"New Instance"** para criar sua primeira instância WhatsApp
4. 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) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.