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

Fonte: [https://nuvits.net/blog/como-instalar-evolution-api-docker-vps](https://nuvits.net/blog/como-instalar-evolution-api-docker-vps)

Publicado em 2026-11-17, por Fernando Chagas.

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.

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

> **O Docker passa por cima do ufw.** Uma porta publicada com `ports:` fica acessível de fora mesmo sem regra no firewall. Por isso só o Caddy publica 80 e 443. A API, o Postgres e o Redis ficam na rede interna do Compose, e a API só escuta em `127.0.0.1`.

## 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:

```ini .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](https://github.com/evolution-foundation/evolution-api/blob/main/docker-compose.yaml): `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.

```yaml 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 Caddyfile
api.example.com {
	reverse_proxy evolution_api:8080
	tls voce@example.com
}
```

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.

> **Nunca rode `docker compose down -v` nesta pasta.** O `-v` apaga os volumes, inclusive as sessões do WhatsApp e o banco.

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](https://nuvits.net/vps-para-evolution-api).
