Skip to content

Tutorial

How to install Evolution API on a VPS (Docker, step by step)

This guide runs Evolution API on an Ubuntu 24.04 VPS: the API, PostgreSQL 15, Redis and Caddy in front, with HTTPS. The Compose file starts from the official one and drops the external Dokploy network, which only exists on that panel and would make docker compose up fail on a plain VPS.

On this page
  1. What you need
  2. Prepare the server
  3. Install Docker
  4. Configure Evolution API
  5. Create the first instance
  6. Update and back up
  7. Next step

What you need

  • An Ubuntu 24.04 64-bit VPS and SSH as a user with sudo.
  • A domain where you can create a DNS record. The examples use api.example.com.
  • An e-mail address for the certificate's ACME account.

Evolution API's documentation asks for PostgreSQL or MySQL and recommends Redis. This guide uses both. Treat 2 vCPU and 4 GB of RAM as the floor for the API, the database and the cache together. With 4 vCPU and 8 GB there is room for more instances and for the database to grow.

At Nuvits you can also order the VPS with Docker already installed. Evolution API itself stays with you: the steps below are the path with a domain and HTTPS.

Prepare the server

If the VPS arrives with root access, create a sudo user and copy your SSH key:

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/

Open another session as deploy and confirm the login before closing the root one. Then allow SSH, HTTP and HTTPS:

bash
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443
sudo ufw enable
sudo ufw status

ufw enable asks for confirmation because it can drop SSH. With the port 22 rule already in place, answer y.

Install Docker

At Nuvits you can order the VPS with Docker already installed. In that case, skip to docker compose version at the end of this section.

The path Docker's documentation recommends for servers is the official apt repository:

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

The commands use sudo docker. The docker group skips sudo, but Docker's documentation warns that it is equivalent to root.

Configure Evolution API

Create the project directory. Its name becomes the volume prefix:

bash
mkdir -p ~/evolution && cd ~/evolution

Generate the global API key. Do not reuse the sample that ships in the repository's .env.example:

bash
openssl rand -hex 16

Create the .env with the key, the public address and the database. SERVER_URL, AUTHENTICATION_API_KEY, DATABASE_PROVIDER, DATABASE_CONNECTION_URI, CACHE_REDIS_ENABLED and CACHE_REDIS_URI are in the current .env.example. POSTGRES_* feeds the official PostgreSQL image:

.env
SERVER_URL=https://api.example.com
AUTHENTICATION_API_KEY=paste-the-key-here

DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://evolution:paste-the-password@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=paste-the-password

The password in DATABASE_CONNECTION_URI and POSTGRES_PASSWORD must match. If the password contains @, :, / or #, percent-encode those characters in the URI, or the client reads the address wrong.

Point api.example.com at the VPS IPv4 before starting Caddy. Without that, the certificate is not issued.

Compose

The file below uses the same images as the official docker-compose.yaml: evoapicloud/evolution-api:latest, postgres:15 and redis:latest. The dokploy-network is left out, because it is external and does not exist on a new VPS. The latest tag is the one the official file uses; to pin a release, replace it with a tag published in the repository before you start.

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

Caddy issues and renews the certificate. Replace the domain and the e-mail:

Caddyfile
api.example.com {
	reverse_proxy evolution_api:8080
	tls [email protected]
}

Start the stack and follow the API until it answers:

bash
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f api

The API container applies the Prisma migrations on startup, according to DATABASE_PROVIDER. If the certificate is not issued, check DNS and ports 80 and 443, then run sudo docker compose restart caddy.

From outside the VPS:

bash
curl -fsS https://api.example.com

The response does not have to be an HTML page. What matters is valid TLS and the API being up. Calls use the apikey header with the value of AUTHENTICATION_API_KEY, as the API documentation describes.

Create the first instance

Evolution API connects through WhatsApp Web, using the Baileys library, or through Meta's official API. Its own documentation warns that the WhatsApp Web connection may have limitations compared with the official API.

With the API up, create the instance through the documented endpoint (POST /instance/create) and read the QR code from GET /instance/connect/{instance}. Open WhatsApp on the phone, under Linked devices, and scan the code. SERVER_URL has to be the public https address, or webhooks point at localhost.

The repository also publishes evoapicloud/evolution-manager, a web panel. It is not in this Compose file: publish it on 127.0.0.1 only and add another Caddy site if you want it. Without that, port 3000 from the official example is open to the internet.

Update and back up

Stop the API, dump the database and the instances directory, and copy both off the 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

The volume name gets the project directory as a prefix (evolution_). Check sudo docker volume ls if tar says the volume does not exist. Copy the .sql, the archive and the .env to your own machine. A copy that stays only on the VPS disk is lost with it.

To update, change the image tag if you pinned one, or pull latest, and recreate only the API:

bash
sudo docker compose pull api
sudo docker compose up -d api
sudo docker compose logs -f api

Read the release notes in the repository first. Pulling latest does not tell you when a change needs a manual database step.

Next step

The VPS, the domain and the certificate stay with you. If you do not have the server yet, see the plans at VPS for Evolution API.