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
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:
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:
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443
sudo ufw enable
sudo ufw statusufw 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:
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 versionThe 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:
mkdir -p ~/evolution && cd ~/evolutionGenerate the global API key. Do not reuse the sample that ships in the repository's .env.example:
openssl rand -hex 16Create 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:
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-passwordThe 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.
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-netCaddy issues and renews the certificate. Replace the domain and the e-mail:
api.example.com {
reverse_proxy evolution_api:8080
tls [email protected]
}Start the stack and follow the API until it answers:
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f apiThe 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:
curl -fsS https://api.example.comThe 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:
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 apiThe 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:
sudo docker compose pull api
sudo docker compose up -d api
sudo docker compose logs -f apiRead 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.