Como instalar a Evolution API em uma VPS Ubuntu

A Evolution API é a solução open-source mais usada no Brasil para integrar WhatsApp com ferramentas como n8n e Chatwoot. Este guia usa Docker Compose com PostgreSQL e Redis — a stack oficial recomendada para produção. Ao final, a API estará rodando em HTTPS com autenticação via API key.

Instalação passo a passo

1. 1

   Atualizar o sistema

   Sincronize repositórios e instale utilitários básicos.

   bashCopiar

   apt update && apt upgrade -y
   apt install -y curl wget git

2. 2

   Instalar Docker e Docker Compose

   Use o script oficial do Docker para instalar a versão CE com o plugin Compose incluído.

   bashCopiar

   curl -fsSL https://get.docker.com -o get-docker.sh
   sh get-docker.sh
   docker --version
   docker compose version

3. 3

   Criar o diretório e clonar a configuração

   Crie o diretório de trabalho para a Evolution API.

   bashCopiar

   mkdir -p /opt/evolution-api
   cd /opt/evolution-api

4. 4

   Criar o arquivo .env

   Gere uma API key segura e preencha as variáveis. O campo AUTHENTICATION_API_KEY protege todos os endpoints da API.

   bashCopiar

   # Gerar API key aleatória
   openssl rand -hex 24

   Dica

   Copie o valor gerado — ele será o AUTHENTICATION_API_KEY no próximo passo.
5. 5

   Configurar variáveis no .env

   Crie o arquivo .env com as variáveis essenciais de produção.

   .envCopiar

   # /opt/evolution-api/.env
   SERVER_URL=https://evo.seudominio.com.br
   SERVER_PORT=8080
   
   # Banco de dados
   DATABASE_PROVIDER=postgresql
   DATABASE_CONNECTION_URI=postgresql://evolution:SUA_SENHA_POSTGRES@evolution-postgres:5432/evolution_db?schema=evolution_api
   
   # Redis
   CACHE_REDIS_ENABLED=true
   CACHE_REDIS_URI=redis://evolution-redis:6379/6
   CACHE_REDIS_PREFIX_KEY=evolution
   
   # Autenticação
   AUTHENTICATION_API_KEY=COLOQUE_AQUI_A_CHAVE_GERADA
   
   # Postgres (usado pelo container evolution-postgres)
   POSTGRES_DATABASE=evolution_db
   POSTGRES_USERNAME=evolution
   POSTGRES_PASSWORD=SUA_SENHA_POSTGRES
   
   LANGUAGE=pt-BR

   Atenção

   Substitua SUA_SENHA_POSTGRES e AUTHENTICATION_API_KEY por valores gerados aleatoriamente. Nunca use os exemplos acima em produção.
6. 6

   Criar o docker-compose.yml

   Esta configuração oficial inclui a API, o gerenciador web (Evolution Manager), PostgreSQL e Redis em uma rede isolada.

   docker-compose.ymlCopiar

   # /opt/evolution-api/docker-compose.yml
   services:
     evolution-api:
       container_name: evolution_api
       image: evoapicloud/evolution-api:latest
       restart: always
       ports:
         - "127.0.0.1:8080:8080"
       volumes:
         - evolution_instances:/evolution/instances
       networks:
         - evolution-net
       env_file: .env
       depends_on:
         - evolution-redis
         - evolution-postgres
   
     evolution-frontend:
       container_name: evolution_frontend
       image: evoapicloud/evolution-manager:latest
       restart: always
       ports:
         - "127.0.0.1:3000:80"
       networks:
         - evolution-net
   
     evolution-redis:
       container_name: evolution_redis
       image: redis:latest
       restart: always
       command: redis-server --port 6379 --appendonly yes
       volumes:
         - evolution_redis:/data
       networks:
         - evolution-net
   
     evolution-postgres:
       container_name: evolution_postgres
       image: postgres:15
       restart: always
       env_file: .env
       environment:
         POSTGRES_DB: ${POSTGRES_DATABASE}
         POSTGRES_USER: ${POSTGRES_USERNAME}
         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
       volumes:
         - postgres_data:/var/lib/postgresql/data
       networks:
         - evolution-net
   
   volumes:
     evolution_instances:
     evolution_redis:
     postgres_data:
   
   networks:
     evolution-net:
       driver: bridge

7. 7

   Subir os containers

   Inicie todos os serviços em background e confirme que a API subiu.

   bashCopiar

   cd /opt/evolution-api
   docker compose up -d
   
   # Aguardar ~30s e verificar status
   docker compose ps
   
   # Acompanhar logs da API
   docker compose logs evolution-api --follow

   Dica

   Aguarde a mensagem "HTTP Server running on port 8080" nos logs antes de prosseguir.
8. 8

   Configurar Nginx como reverse proxy

   Instale o Nginx e crie um virtual host que encaminha requisições para a Evolution API na porta 8080.

   bashCopiar

   apt install -y nginx
   
   cat > /etc/nginx/sites-available/evolution-api << 'NGINXEOF'
   server {
       listen 80;
       server_name evo.seudominio.com.br;
       return 301 https://$host$request_uri;
   }
   
   server {
       listen 443 ssl;
       server_name evo.seudominio.com.br;
   
       ssl_certificate /etc/letsencrypt/live/evo.seudominio.com.br/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/evo.seudominio.com.br/privkey.pem;
   
       location / {
           proxy_pass http://127.0.0.1:8080;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_read_timeout 3600s;
       }
   }
   NGINXEOF
   
   ln -s /etc/nginx/sites-available/evolution-api /etc/nginx/sites-enabled/evolution-api
   nginx -t

   Atenção

   Substitua evo.seudominio.com.br pelo seu subdomínio real.
9. 9

   Obter certificado SSL com Certbot

   Emita um certificado Let's Encrypt gratuito para o domínio.

   bashCopiar

   apt install -y certbot python3-certbot-nginx
   
   certbot --nginx \
     -d evo.seudominio.com.br \
     --non-interactive \
     --agree-tos \
     --email seu@email.com
   
   systemctl reload nginx

10. 10

    Configurar firewall UFW

    Libere apenas SSH, HTTP e HTTPS. A porta 8080 permanece fechada externamente.

    bashCopiar

    ufw allow 22/tcp comment 'SSH'
    ufw allow 80/tcp comment 'HTTP'
    ufw allow 443/tcp comment 'HTTPS'
    ufw --force enable
    ufw status verbose

11. 11

    Verificar a instalação

    Teste a API via curl usando a API key configurada.

    bashCopiar

    # Verificar endpoint de saúde
    curl -s https://evo.seudominio.com.br/ | head -c 200
    
    # Listar instâncias (substitua pela sua API key)
    curl -s https://evo.seudominio.com.br/instance/fetchInstances \
      -H "apikey: SUA_API_KEY_AQUI"

    Dica

    A resposta deve retornar um array JSON. Se retornar 401, a API key no header está incorreta.

Troubleshooting

Perguntas frequentes