How to Host Evolution API & WhatsApp Bot on a Linux VPS with Docker

WhatsApp has become the primary customer conversion and support channel for modern businesses. However, relying on official WhatsApp Cloud API providers incurs steep per-conversation fees and restrictive 24-hour customer service messaging windows. Self-hosting Evolution API v2 on a private WhatsApp Bot VPS allows you to connect unlimited WhatsApp numbers, send automated order alerts, and integrate AI chatbot workflows at zero per-message cost.

In this tutorial, we configure an Ubuntu KVM VPS, set up Docker and Docker Compose, deploy the Evolution API stack with PostgreSQL and Redis, and connect it to n8n and Typebot for automated lead qualification.

Why Self-Host Evolution API on a Dedicated VPS?

• Zero Per-Message Billing: Send unlimited order receipts, shipping notifications, and CRM alerts without paying per-conversation fees to Meta or third-party BSPs.
• Multi-Instance Support: Connect 10+ separate WhatsApp numbers (Sales, Support, Billing) on a single server instance.
• REST & Webhook API: Send text messages, PDF invoices, audio notes, and location pins via simple cURL or POST webhooks.
• Native AI Integration: Connect directly to Typebot, Chatwoot, and n8n workflow automation to build intelligent AI support agents.

Server Sizing Requirements

Because Evolution API runs headless Chromium instances to manage WhatsApp Web sessions, we recommend the following minimum specs:

• 1 to 3 WhatsApp Instances: 2 vCPU Cores • 4 GB RAM • 60 GB NVMe (Hostinap USVPS1 / EUVPS1).
• 5 to 15 WhatsApp Instances (Agencies): 4 vCPU Cores • 8 GB RAM • 120 GB NVMe (Hostinap USVPS2 / EUVPS2).

Step 1: Installing Docker & Docker Compose on Ubuntu

Connect to your VPS via SSH as root and run the official Docker repository installation script:

# Update package list and install prerequisites
apt-get update && apt-get install -y curl git ufw

# Install Docker Engine
curl -fsSL https://get.docker.com | sh

# Verify Docker installation
docker --version && docker compose version

Step 2: Creating the docker-compose.yml File

Create a dedicated directory for your WhatsApp automation stack:

mkdir -p /opt/evolution-api && cd /opt/evolution-api
nano docker-compose.yml

Paste the following complete production Docker Compose configuration:

version: '3.8'

services:
  evolution-api:
    image: atendai/evolution-api:v2.1.2
    restart: always
    ports:
      - "8080:8080"
    environment:
      - SERVER_URL=https://whatsapp.yourdomain.com
      - AUTHENTICATION_API_KEY=YourSuperSecretMasterApiKey123!
      - DATABASE_PROVIDER=postgresql
      - DATABASE_CONNECTION_URI=postgresql://evolution:secretdbpass@postgres:5432/evolution_db?schema=public
      - CACHE_REDIS_ENABLED=true
      - CACHE_REDIS_URI=redis://redis:6379
      - WEBHOOK_GLOBAL_ENABLED=true
    volumes:
      - evolution_instances:/evolution/instances
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:15-alpine
    restart: always
    environment:
      - POSTGRES_USER=evolution
      - POSTGRES_PASSWORD=secretdbpass
      - POSTGRES_DB=evolution_db
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    restart: always
    volumes:
      - redis_data:/data

volumes:
  evolution_instances:
  postgres_data:
  redis_data:

Step 3: Launching the Stack

Start your containers in detached background mode:

docker compose up -d

Verify that all three services (Evolution API, PostgreSQL, and Redis) show as healthy and running:

docker compose ps

Step 4: Creating Your First WhatsApp Instance

You can now interact with your server API to create an instance and generate a pairing QR code:

curl -X POST http://YOUR_SERVER_IP:8080/instance/create \
  -H "apikey: YourSuperSecretMasterApiKey123!" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "support_bot",
    "token": "bot_token_secret",
    "qrcode": true
  }'

Open the returned base64 QR code in your browser, scan it using WhatsApp on your phone under Linked Devices → Link a Device, and your bot session will immediately connect!

Step 5: Sending an Automated WhatsApp Order Alert

To send an automated text message with order details from WooCommerce, Shopify, or Python:

curl -X POST http://YOUR_SERVER_IP:8080/message/sendText/support_bot \
  -H "apikey: YourSuperSecretMasterApiKey123!" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "13299995554",
    "text": "Hi Alex! 🎉 Your Hostinap server order #9841 has been provisioned successfully."
  }'

Connecting to n8n & AI Chatbots

By pairing Evolution API with our n8n Workflow Automation VPS, you can construct complex visual workflows: incoming customer messages route to DeepSeek-R1 or OpenAI to answer inquiries, check inventory levels in Google Sheets, or hand off complex issues to live human agents in Chatwoot.

Summary & Free Setup Support

Running your WhatsApp infrastructure on a dedicated KVM VPS gives you complete freedom, high throughput, and zero per-message SaaS fees.

Explore our WhatsApp Bot & Evolution API VPS plans starting at \$12/mo — our DevOps engineers will configure Docker Compose, SSL reverse proxies, and your Evolution API instance completely free of charge!