You install Evolution API on a VPS with Docker Compose: one file describes the services (the API, the database and, in many guides, Redis), a second file holds the settings, and one command brings it all up. What this article does not do is copy the compose file, because it changes with each version. The right file is in the project’s official documentation, and that is where you should take it from.
Before you start
| You need |
Why |
| A VPS with root access |
Evolution API does not run on shared hosting, which has no Docker. See first steps with your VPS. |
| An operating system with good documentation |
Ubuntu 22.04 LTS has the most. See which operating system to choose. |
| Docker and Docker Compose |
If you do not have them yet, start with installing Docker and Docker Compose. |
| A domain or subdomain |
To put HTTPS in front of the API. It can come later, but do not leave the API open in the meantime. |
Step by step
| 1 |
Connect to the VPS over SSH and create a folder for this project alone, for example evolution. Everything that follows lives inside it, which makes backups easier.
|
|
| 2 |
Get the compose file from Evolution API’s official documentation, along with the example settings file that goes with it. Check that the example matches the version of the image you are going to use.
|
|
| 3 |
Generate the API key. The AUTHENTICATION_API_KEY setting protects every request. Make it random, for instance with openssl rand -hex 32, and write it into the settings file. Never publish it.
|
|
| 4 |
Pick the database. PostgreSQL or MySQL, according to the documentation. Use a strong password, different from the API key. If the example includes Redis, leave it in.
|
|
| 5 |
Check the volumes. The compose file must keep the instances and the database in volumes. Without them a restart wipes the sessions and you scan every QR code again.
|
|
| 6 |
Bring the services up with docker compose up -d, in the project folder.
|
|
| 7 |
See whether they started. docker compose ps lists the services and docker compose logs -f follows the logs. Look for database connection errors or missing settings.
|
|
|
Do not leave the API exposed and unprotected. Until you have HTTPS and a firewall, the key is the only barrier. Docker publishes ports by editing the network rules itself, so an ordinary firewall may not hide them. Read securing Evolution API.
|
When something goes wrong
| Symptom |
Where to look |
| The API service restarts over and over |
The logs: database unreachable, a setting missing, or a password that differs between the files. |
| The database will not start |
Disk space and volume permissions. See Docker filling the disk. |
| You cannot reach the API from outside |
The port and the firewall. See ports and firewall on a VPS. |
| Everything is lost on restart |
The persistent volume is missing. Fix the compose file before linking any number. |
Do not use docker compose down -v to “clean up”. The -v option deletes the volumes, and with them the database and the sessions. To stop the services without losing data, plain docker compose down is enough.
|
RECOMMENDED PRODUCT VPS server with root access Resources of your own, the OS you choose, reinstall whenever you like. from 7.560,00 Kz/mo (3-year plan, with coupon) See plans |
Português
English
