Prerequisites: Before proceeding with the installation of Evolution API v2 using Docker, make sure you have already configured the necessary services, such as PostgreSQL and Redis. Follow the links below for more details:

These installation instructions assume that you have already installed Docker on your machine. You can find information on how to install Docker in the
Official Docker Documentation.

Evolution API v2 is Docker-ready and can be easily deployed with Docker in standalone or swarm mode. The official Evolution API repository contains all the necessary composition files to install and run the API.

​
Docker Compose

Deploying Evolution API v2 using Docker Compose simplifies the setup and management of your Docker containers. It allows you to define your Docker environment in a docker-compose.yaml file and then use a single command to start everything.

​
Docker Compose File

The following example illustrates how to configure Docker Compose for standalone environments, i.e., a single running server. For syncing two servers in parallel or for greater scalability, use Docker Swarm, recommended for more advanced users.

​
Standalone Configuration

Attention: The commands described here as docker compose may not work in older versions of Docker. If you are using an older version, replace with docker-compose.

Docker standalone is suitable when Evolution API will run on just one machine, without the need for immediate scalability. This is the most convenient method for most users.

To get started, create a docker-compose.yml file with the following content:

version: '3.9'
services:
  evolution-api:
    container_name: evolution_api
    image: atendai/evolution-api:v2.1.1
    restart: always
    ports:
      - "8080:8080"
    env_file:
      - .env
    volumes:
      - evolution_instances:/evolution/instances

volumes:
  evolution_instances:

Next, create a .env file in the same directory with the following minimal content:

AUTHENTICATION_API_KEY=change-me

For more configurations, you can get the example file from the official repository. Also, check the environment variables guide here.

​
Starting the API

Navigate to the directory containing the docker-compose.yml file and run the following command to start the services defined in the file:

docker compose up -d

This command will download the necessary Docker images, create the defined services, networks, and volumes, and start the Evolution API service.

​
Checking the Logs

After running the docker compose up command, you can check the logs to confirm that the services are running correctly:

docker logs evolution_api

​
Stopping the Service

To stop the service, use the command:

docker compose down

​
Accessing the API

Open your browser and go to http://localhost:8080 to check if the Evolution API is operational.

​
Docker Swarm

To set up and manage a Docker Swarm cluster for Evolution API v2, follow the instructions below. Docker Swarm is ideal for environments that require scalability and high availability.

​
Docker Swarm Installation

​
Configuring the Manager Server

If you are using a Hetzner server, run:

sudo apt-get update && apt-get install -y apparmor-utils

Step 1: Hostname Configuration

  1. Change the machine’s hostname to identify it in the cluster:
hostnamectl set-hostname manager1
  1. Edit the /etc/hosts file to add the new name:
nano /etc/hosts

Add the line:

127.0.0.1    manager1
  1. Reboot the system to apply the changes:
reboot
  1. Check the hostname:
hostnamectl

Step 2: Docker Installation

Install Docker by running:

curl -fsSL https://get.docker.com | bash

Step 3: Starting the Swarm

Start Docker Swarm:

docker swarm init --advertise-addr IP_SERVER

Step 4: Docker Swarm Network Configuration

Create the overlay network for Docker Swarm:

docker network create --driver=overlay network_public

Note the command generated to register the Workers:

docker swarm join --token HASH IP_SERVER:2377

​
Configuring the Worker Server

If you are using a Hetzner server, run:

sudo apt-get update && apt-get install -y apparmor-utils

Step 1: Hostname Configuration

  1. Change the machine’s hostname to identify it in the cluster:
hostnamectl set-hostname worker1
  1. Edit the /etc/hosts file to add the new name:
nano /etc/hosts

Add the line:

127.0.0.1    worker1
  1. Reboot the system to apply the changes:
reboot

Step 2: Docker Installation

Install Docker by running:

curl -fsSL https://get.docker.com | bash

Step 3: Adding the Worker to the Cluster

Run the previously obtained command to add the Worker to the cluster:

docker swarm join --token HASH IP_SERVER:2377

​
Prerequisites for Evolution API via Swarm

​
Installing Traefik

To install Traefik on Docker Swarm, follow the instructions below:

  1. On the manager server, create a traefik.yaml file:
nano traefik.yaml
  1. Add the following content to the file:
version: "3.7"

services:
  traefik:
    image: traefik:2.11.2
    command:
      - "--api.dashboard=true"
      - "--providers.docker.swarmMode=true"
      - "--providers.docker.endpoint=unix:///var/run/docker.sock"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=network_public"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
      - "--entrypoints.web.http.redirections.entryPoint.scheme=https"
      - "--entrypoints.web.http.redirections.entrypoint.permanent=true"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.letsencryptresolver.acme.httpchallenge=true"
      - "--certificatesresolvers.letsencryptresolver.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.letsencryptresolver.acme.email=your@email.com"
      - "--certificatesresolvers.letsencryptresolver.acme.storage=/etc/traefik/letsencrypt/acme.json"
      - "--log.level=DEBUG"
      - "--log.format=common"
      - "--log.filePath=/var/log/traefik/traefik.log"
      - "--accesslog=true"
      - "--accesslog.filepath=/var/log/traefik/access-log"
    deploy:
      placement:
        constraints:
          - node.role == manager
      restart_policy:
        condition: on-failure
        delay: 5s
      labels:
        - "traefik.enable=true"
        - "traefik.http.middlewares.redirect-https.redirectscheme.scheme=https"
        - "traefik.http.middlewares.redirect-https.redirectscheme.permanent=true"
        - "traefik.http.routers.http-catchall.rule=hostregexp(`{host:.+}`)"
        - "traefik.http.routers.http-catchall.entrypoints=web"
        - "traefik.http.routers.http-catchall.middlewares=redirect-https@docker"
        - "traefik.http.routers.http-catchall.priority=1"
    volumes:
      - "/var/run

/docker.sock:/var/run/docker.sock:ro"
      - "vol_certificates:/etc/traefik/letsencrypt"
    ports:
      - target: 80
        published: 80
        mode: host
      - target: 443
        published: 443
        mode: host
    networks:
      - network_public

volumes:
  vol_certificates:
    external: true
    name: volume_swarm_certificates

networks:
  network_public:
    external: true
    name: network_public
  1. Run the following command to deploy the Traefik stack:
docker stack deploy --prune --resolve-image always -c traefik.yaml traefik

​
Deploying Evolution API v2

Finally, to deploy Evolution API v2 on Docker Swarm, use the configuration file available here with the following content:

version: "3.7"

services:
  evolution_v2:


    image: atendai/evolution-api:v2.1.1
    volumes:
      - evolution_instances:/evolution/instances
    networks:
      - network_public
    environment:
      - SERVER_URL=https://evo2.site.com
      - DEL_INSTANCE=false
      - DATABASE_ENABLED=true
      - DATABASE_PROVIDER=postgresql
      - DATABASE_CONNECTION_URI=postgresql://postgres:PASSWORD@postgres:5432/evolution
      - DATABASE_SAVE_DATA_INSTANCE=true
      - DATABASE_SAVE_DATA_NEW_MESSAGE=true
      - DATABASE_SAVE_MESSAGE_UPDATE=true
      - DATABASE_SAVE_DATA_CONTACTS=true
      - DATABASE_SAVE_DATA_CHATS=true
      - DATABASE_SAVE_DATA_LABELS=true
      - DATABASE_SAVE_DATA_HISTORIC=true
      - DATABASE_CONNECTION_CLIENT_NAME=evolution_v2
      - RABBITMQ_ENABLED=false
      - RABBITMQ_URI=amqp://admin:admin@rabbitmq:5672/default
      - CACHE_REDIS_ENABLED=true
      - CACHE_REDIS_URI=redis://evo_redis:6379/1
      - CACHE_REDIS_PREFIX_KEY=evolution_v2
      - CACHE_REDIS_SAVE_INSTANCES=false
      - CACHE_LOCAL_ENABLED=false
      - S3_ENABLED=true
      - S3_ACCESS_KEY=
      - S3_SECRET_KEY=
      - S3_BUCKET=evolution
      - S3_PORT=443
      - S3_ENDPOINT=files.site.com
      - S3_USE_SSL=true
      - AUTHENTICATION_API_KEY=429683C4C977415CAAFCCE10F7D57E11
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints:
          - node.hostname == evolution-manager
      labels:
        - traefik.enable=true
        - traefik.http.routers.evolution_v2.rule=Host(`evo2.site.com`)
        - traefik.http.routers.evolution_v2.entrypoints=websecure
        - traefik.http.routers.evolution_v2.tls.certresolver=letsencryptresolver
        - traefik.http.routers.evolution_v2.service=evolution_v2
        - traefik.http.services.evolution_v2.loadbalancer.server.port=8080
        - traefik.http.services.evolution_v2.loadbalancer.passHostHeader=true

volumes:
  evolution_instances:
    external: true
    name: evolution_v2_data

networks:
  network_public:
    external: true
    name: network_public

After configuring and saving the file, deploy the stack with the command:

docker stack deploy --prune --resolve-image always -c evolution_api_v2.yaml evolution_v2

​
Accessing the API

Open your browser and go to https://evo2.site.com to check if the Evolution API is operational.