--- title: "Host Evolution API (WhatsApp) on a VPS with Docker | StreetHosting" description: "Run Evolution API with Docker Compose, PostgreSQL and Redis, pair WhatsApp with the QR Code, put Nginx with HTTPS in front and connect it to n8n." url: "https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps" type: "page" language: "en-US" --- VPS · 9 min · Advanced Published on Nov 13, 2026 · Updated on Nov 13, 2026 # Evolution API on a VPS: WhatsApp with Docker Compose, PostgreSQL and Redis Evolution API is an open source WhatsApp API, widely used with n8n and Chatwoot. See how to run it with Docker Compose, pair it with the QR Code, publish it over HTTPS and what the risks of an unofficial connection are. By [Equipe StreetHosting](https://streethosting.com.br/en/autores#equipe-streethosting) · StreetHosting infrastructure and support team [Databases](https://streethosting.com.br/en/guides/topics/databases) [Containers and Docker](https://streethosting.com.br/en/guides/topics/docker) [Network, DNS and domains](https://streethosting.com.br/en/guides/topics/networking) [Certificates and HTTPS](https://streethosting.com.br/en/guides/topics/ssl) Summarize with: [](https://chat.openai.com/?q=Summarize%20the%20key%20points%20of%20this%20StreetHosting%20guide%3A%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fhost-evolution-api-whatsapp-vps.%20Highlight%20the%20step-by-step%20instructions%2C%20the%20prerequisites%20and%20the%20most%20common%20mistakes. "ChatGPT") [](https://claude.ai/new?q=Summarize%20the%20key%20points%20of%20this%20StreetHosting%20guide%3A%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fhost-evolution-api-whatsapp-vps.%20Highlight%20the%20step-by-step%20instructions%2C%20the%20prerequisites%20and%20the%20most%20common%20mistakes. "Claude") [](https://www.google.com/search?udm=50&aep=11&q=Summarize%20the%20key%20points%20of%20this%20StreetHosting%20guide%3A%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fhost-evolution-api-whatsapp-vps.%20Highlight%20the%20step-by-step%20instructions%2C%20the%20prerequisites%20and%20the%20most%20common%20mistakes. "Google AI Mode") [](https://x.com/i/grok?text=Summarize%20the%20key%20points%20of%20this%20StreetHosting%20guide%3A%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fhost-evolution-api-whatsapp-vps.%20Highlight%20the%20step-by-step%20instructions%2C%20the%20prerequisites%20and%20the%20most%20common%20mistakes. "Grok") [](https://www.perplexity.ai/search/new?q=Summarize%20the%20key%20points%20of%20this%20StreetHosting%20guide%3A%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fhost-evolution-api-whatsapp-vps.%20Highlight%20the%20step-by-step%20instructions%2C%20the%20prerequisites%20and%20the%20most%20common%20mistakes. "Perplexity") Share: [](https://x.com/intent/tweet?text=Host%20Evolution%20API%20%28WhatsApp%29%20on%20a%20VPS%20with%20Docker&url=https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fhost-evolution-api-whatsapp-vps "Share on X") [](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fhost-evolution-api-whatsapp-vps "Share on Facebook") [](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fhost-evolution-api-whatsapp-vps "Share on LinkedIn") [](https://wa.me/?text=Host%20Evolution%20API%20%28WhatsApp%29%20on%20a%20VPS%20with%20Docker%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fhost-evolution-api-whatsapp-vps "Share on WhatsApp") For agents: Copy as Markdown [.md](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps.md) In this guide 8 sections * [What Evolution API is and the real risk](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#o-que-e) * [Prepare the VPS](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#preparar) * [Docker Compose with PostgreSQL and Redis](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#compose) * [The main variables](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#variaveis) * [Create the instance and read the QR Code](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#parear) * [Nginx with HTTPS in front](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#nginx) * [Connect it to n8n](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#n8n) * [Where to run this at StreetHosting](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#onde-rodar) Quick answer **Evolution API** is an open source WhatsApp API: you connect a number through the QR Code and start sending and receiving messages over HTTP, which pairs well with n8n and Chatwoot. On a VPS it runs with Docker Compose alongside PostgreSQL and Redis, protected by a global API key and published with Nginx and HTTPS. Before you start, know that it is an **unofficial**connection: the number can be banned. Use a dedicated number and avoid mass messaging. The official route is Meta's WhatsApp Business API. ## What Evolution API is and the real risk[](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#o-que-e) Evolution API is a server that sits between your system and WhatsApp. It keeps a WhatsApp Web session connected to your number and exposes a REST API: you call an address to send a text, image or audio message, and you set a webhook to be told about every message that arrives. That is why it shows up so often in support automations, with n8n for the logic and Chatwoot for the inbox. This is an unofficial connection to WhatsApp. Meta does not authorize this kind of use and can ban the number, sometimes without warning. Never use your personal number or your company's main one. Register a number dedicated to the project, do not send mass messages, do not message people who have never talked to you and keep a pace similar to a person's. If your business depends on WhatsApp and cannot take that risk, the official alternative is Meta's WhatsApp Business API (Cloud API). It requires a verified business account, company-initiated messages through approved templates and charges for those messages. It takes more work to start and it is the path Meta supports. With that settled, the rest of the guide is technical: how to keep Evolution API running reliably on your VPS. ## Prepare the VPS[](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#preparar) You need a VPS with Ubuntu, Docker and the Compose plugin, a domain or subdomain pointing at the VPS IP (for example `api.yourdomain.com`) and Nginx installed for HTTPS. If you do not have Docker yet, follow the [guide to installing Docker on Ubuntu](https://streethosting.com.br/en/guides/vps/install-docker-ubuntu-vps). To understand the files that come next, the [Docker Compose guide](https://streethosting.com.br/en/guides/vps/docker-compose-vps-guide) explains the structure. On size: for one or two instances, 2 GB of RAM works, but with little headroom, since the API, PostgreSQL and Redis share the memory. Prefer 4 GB if you plan to grow. `mkdir -p ~/evolution && cd ~/evolution openssl rand -hex 24 # generates a random key for AUTHENTICATION_API_KEY openssl rand -hex 16 # generates another one for the PostgreSQL password` ## Docker Compose with PostgreSQL and Redis[](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#compose) Evolution API's image name, tag and variables change between versions. The file below is a minimal starting point based on the official documentation (doc.evolution-api.com and the EvolutionAPI/evolution-api repository on GitHub) for the 2.x line. Tag v2.3.7 was the newest stable release on Docker Hub (evoapicloud/evolution-api) in November 2026. Before you start it, check whether a newer one is out and read the `.env.example` file of the version you choose. Do not use the latest tag in production: pin the version. Create the `docker-compose.yml` file: `services: evolution-api: container_name: evolution_api image: evoapicloud/evolution-api:v2.3.7 restart: always depends_on: - postgres - redis ports: - "127.0.0.1:8080:8080" env_file: - .env volumes: - evolution_instances:/evolution/instances postgres: image: postgres:15 container_name: evolution_postgres restart: always environment: POSTGRES_DB: evolution_db POSTGRES_USER: evolution POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - postgres_data:/var/lib/postgresql/data redis: image: redis:7 container_name: evolution_redis restart: always command: redis-server --appendonly yes volumes: - evolution_redis:/data volumes: evolution_instances: postgres_data: evolution_redis:` Port 8080 is bound to 127.0.0.1: the API cannot be reached directly from the internet, only through the Nginx we will set up. PostgreSQL and Redis do not publish any port at all, only the API talks to them over Compose's internal network. ## The main variables[](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#variaveis) In the same directory, create the `.env` file. This is the minimum set for version 2: `SERVER_URL=https://api.yourdomain.com SERVER_PORT=8080 AUTHENTICATION_API_KEY=PASTE_THE_FIRST_KEY_HERE POSTGRES_PASSWORD=PASTE_THE_SECOND_KEY_HERE DATABASE_PROVIDER=postgresql DATABASE_CONNECTION_URI=postgresql://evolution:PASTE_THE_SECOND_KEY_HERE@postgres:5432/evolution_db?schema=evolution_api DATABASE_SAVE_DATA_INSTANCE=true DATABASE_SAVE_DATA_NEW_MESSAGE=true DATABASE_SAVE_DATA_CONTACTS=true DATABASE_SAVE_DATA_CHATS=true CACHE_REDIS_ENABLED=true CACHE_REDIS_URI=redis://redis:6379/6 CACHE_REDIS_PREFIX_KEY=evolution CACHE_REDIS_SAVE_INSTANCES=false CACHE_LOCAL_ENABLED=false` * **AUTHENTICATION\_API\_KEY:**the global key. Whoever has it controls every instance, so treat it like a password, use a long random value and never put it in a website's code. * **SERVER\_URL:** the public address of the API, with https. It is used to build links the API itself returns, so put the final domain. * **DATABASE\_PROVIDER and DATABASE\_CONNECTION\_URI:** say the database is PostgreSQL and how to reach it. The host is the Compose service name (postgres), never localhost, because each container has its own localhost. * **CACHE\_REDIS\_\*:** turn on the Redis cache. The host is also the service name (redis). Protect the file and start everything: `chmod 600 .env docker compose up -d docker compose logs -f evolution-api` In the logs, wait for the API to report that it is listening on port 8080 and has connected to the database. On the first start the image prepares the tables in PostgreSQL, so it can take a while. If a database connection error appears, check the password in the URI and whether PostgreSQL has finished starting. ## Create the instance and read the QR Code[](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#parear) Each WhatsApp number is an **instance**. You create one by calling the API with the global key in the `apikey` header. For now the API only answers inside the VPS, so run this on the machine itself: `curl -X POST http://127.0.0.1:8080/instance/create \ -H "apikey: YOUR_GLOBAL_KEY" \ -H "Content-Type: application/json" \ -d '{"instanceName": "support", "integration": "WHATSAPP-BAILEYS", "qrcode": true}'` The response carries the QR Code (in base64) and the instance waits to be scanned. To ask for the QR Code again, call `GET /instance/connect/support` with the same header. Since reading a base64 image in the terminal is awkward, the most practical way is the web panel, Evolution Manager, which shows the QR Code as an image. In the official repository's docker-compose.yaml it is a separate service; check your version's documentation for how to publish it, and do not leave it open to the internet without protection. 1. On the phone with the dedicated number, open WhatsApp and go to Linked devices. 2. Tap Link a device. 3. Scan the instance's QR Code before it expires. The code changes within seconds and the API limits the attempts. 4. Confirm the connection state with `GET /instance/connectionState/support`: the expected value is open. To test sending, a text message looks like this. The number goes with country code and area code, with no spaces or symbols: `curl -X POST http://127.0.0.1:8080/message/sendText/support \ -H "apikey: YOUR_GLOBAL_KEY" \ -H "Content-Type: application/json" \ -d '{"number": "5511999999999", "text": "Evolution API test"}'` The paths and fields above follow the 2.x documentation, but they may change from version to version. On a 404 error or a rejected field, compare with the API reference in the official documentation. ## Nginx with HTTPS in front[](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#nginx) For n8n, Chatwoot or a website to call the API from outside, publish port 8080 through Nginx with HTTPS. The proxy walkthrough is in the [Nginx reverse proxy guide](https://streethosting.com.br/en/guides/vps/nginx-reverse-proxy-vps) and the certificate one is in the [Let's Encrypt SSL guide](https://streethosting.com.br/en/guides/vps/lets-encrypt-ssl-certificate-vps). The site block looks like this: `server { server_name api.yourdomain.com; location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; 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_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 120s; client_max_body_size 50m; } }` The Upgrade and Connection headers allow WebSocket, and `client_max_body_size` lets image and file uploads through. After enabling the site and issuing the certificate, test from outside with `curl -H "apikey: YOUR_GLOBAL_KEY" https://api.yourdomain.com/instance/fetchInstances`. Without the key, the API refuses the call. Since the global key gives full control, consider allowing access to the API only from the IPs that need it, with the [UFW firewall](https://streethosting.com.br/en/guides/vps/ufw-firewall-ubuntu-vps) or with allow rules in Nginx. And keep the key in a password manager. ## Connect it to n8n[](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#n8n) n8n comes in on both sides. To **receive** messages, create a workflow that starts with a Webhook node (POST method), copy its production URL and register that URL as the instance webhook, with the received message event turned on. Evolution API then sends a POST to n8n for every message, with the number, the text and the contact data. The webhook fields have changed between versions, so set it up through Evolution Manager or follow the reference for your version. To **send**, use an HTTP Request node with the POST method to `/message/sendText/INSTANCE_NAME`, the apikey header and a JSON body with number and text, the same fields as the test you ran earlier. Store the key in an n8n credential instead of leaving it written in the workflow. If n8n is on the same VPS, put both on the same Docker network and call the API by its service name (for example `http://evolution-api:8080`) instead of going through the internet. The n8n installation is in the [guide to n8n on a VPS](https://streethosting.com.br/en/guides/vps/host-n8n-vps-brazil). Automating replies is different from blasting a list. Workflows that answer people who wrote first, at a moderate pace, are far less risky than campaigns to cold contacts. Put an interval between messages and a daily limit in your workflow. ## Where to run this at StreetHosting[](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#onde-rodar) Evolution API runs as a container and needs Docker and an Nginx with a certificate, so what fits is a VPS with root access. On StreetHosting VPS plans the virtualization is KVM, with a dedicated IPv4, AntiDDoS included and servers in São Paulo, with automatic activation in about 60 seconds after payment by Pix or card. For the API with PostgreSQL and Redis and n8n on the same machine, the Xeon VPS with 2 vCPU and 2 GB of RAM, from R$ 26.00 per month, is enough to start with one instance. If you plan several instances, a large message history or other applications alongside, move up to a [Ryzen VPS](https://streethosting.com.br/en/vps/ryzen) with more memory. In this guide * [What Evolution API is and the real risk](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#o-que-e) * [Prepare the VPS](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#preparar) * [Docker Compose with PostgreSQL and Redis](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#compose) * [The main variables](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#variaveis) * [Create the instance and read the QR Code](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#parear) * [Nginx with HTTPS in front](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#nginx) * [Connect it to n8n](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#n8n) * [Where to run this at StreetHosting](https://streethosting.com.br/en/guides/vps/host-evolution-api-whatsapp-vps#onde-rodar) ## Frequently asked questions Is Evolution API an official WhatsApp product? No. Evolution API connects to WhatsApp Web by imitating the app, and that is not a channel authorized by Meta. Meta can block the number at any time. The official alternative is Meta's WhatsApp Business API, which requires a business account and approved templates, and charges for the template messages the business sends. Can my number be banned for using Evolution API? It can. The risk grows with mass messaging, messages to people who do not know the number, many identical messages and newly created numbers. Use a number dedicated to the project, reply to people who wrote first, keep a human pace and do not use the tool for spam. How much memory does Evolution API need? For a few instances, a 2 GB VPS runs the API, PostgreSQL and Redis together, with little headroom. Each connected instance uses memory, and the message history in the database grows over time. For several instances, prefer 4 GB or more and watch consumption. Do I need PostgreSQL and Redis to run it? Version 2 uses a relational database (PostgreSQL or MySQL) to store instances and messages, and Redis works as a cache. The official documentation describes PostgreSQL as the recommended path. Check the documentation for the version you install, because the variables change between versions. How does n8n talk to Evolution API? In two ways. To receive messages, you point the instance webhook at an n8n Webhook node. To send, n8n uses the HTTP Request node calling the Evolution API with the key in the apikey header. If both are on the same VPS and the same Docker network, use the service name instead of the public address. Next step See VPS plans Root VPS in Brazil with NVMe and Anti-DDoS. [See VPS plans](https://streethosting.com.br/en/vps) ## Related guides [VPS Intermediate Host n8n on a VPS in Brazil: low-latency automation and best practices Hosting n8n on a VPS in Brazil helps with integrations that depend on local APIs and predictable response times. This guide covers a Docker-based architecture, a TLS proxy, credential protection and a backup strategy so you never lose your workflows. 4 min Read guide](https://streethosting.com.br/en/guides/vps/host-n8n-vps-brazil) [VPS Intermediate How to install Docker on Ubuntu 22.04 or 24.04 on a VPS (straight to the point) A stable Docker install on an Ubuntu VPS depends on the right package source and step by step validation. In this guide you set up the official repository, install Engine and Compose, test the daemon and apply basic security measures before deploying applications. 3 min Read guide](https://streethosting.com.br/en/guides/vps/install-docker-ubuntu-vps) [VPS Intermediate How to set up Nginx as a reverse proxy on a VPS Your app runs on an internal port and you want to serve it on a domain with HTTPS. Nginx as a reverse proxy solves that and also brings several apps together in one place. 3 min Read guide](https://streethosting.com.br/en/guides/vps/nginx-reverse-proxy-vps) [← Back to the Guide Center](https://streethosting.com.br/en/guides)