Installation

Overview

Evolution API can be installed in multiple ways depending on your needs. This guide covers Docker installation (recommended), manual installation with npm, and production deployment configurations.

Evolution API requires Node.js 20+, PostgreSQL or MySQL, and Redis for production use.

Docker installation (recommended)

Docker provides the fastest and most reliable way to run Evolution API with all dependencies pre-configured.

Prerequisites

Ensure you have installed:

Docker (version 20.10 or higher)
Docker Compose (version 2.0 or higher)
At least 2GB of available RAM
5GB of free disk space

Installation steps

Clone the repository

git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api

Configure environment variables

Copy the example environment file:

cp .env.example .env

Edit .env with your preferred text editor. Here are the essential variables:

.env

# Server Configuration
SERVER_NAME=evolution
SERVER_TYPE=http
SERVER_PORT=8080
SERVER_URL=http://localhost:8080

# Authentication
AUTHENTICATION_API_KEY=your-secure-api-key-here
AUTHENTICATION_EXPOSE_IN_FETCH_INSTANCES=true

# Database Provider: postgresql | mysql
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI='postgresql://postgres:postgres@evolution-postgres:5432/evolution_db?schema=evolution_api'
DATABASE_CONNECTION_CLIENT_NAME=evolution_exchange

# Save Data Options
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

# Redis Cache
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://evolution-redis:6379/6
CACHE_REDIS_PREFIX_KEY=evolution
CACHE_REDIS_SAVE_INSTANCES=false

# CORS Configuration
CORS_ORIGIN=*
CORS_METHODS=GET,POST,PUT,DELETE
CORS_CREDENTIALS=true

# Logging
LOG_LEVEL=ERROR,WARN,DEBUG,INFO,LOG,VERBOSE,DARK,WEBHOOKS
LOG_COLOR=true
LOG_BAILEYS=error

# WhatsApp Session
CONFIG_SESSION_PHONE_CLIENT=Evolution API
CONFIG_SESSION_PHONE_NAME=Chrome

# QR Code Configuration
QRCODE_LIMIT=30
QRCODE_COLOR='#175197'

# Telemetry (optional)
TELEMETRY_ENABLED=true

View all environment variables

Evolution API supports over 100 configuration options. Here are additional important variables:Webhooks:

WEBHOOK_GLOBAL_ENABLED=false
WEBHOOK_GLOBAL_URL=''
WEBHOOK_EVENTS_QRCODE_UPDATED=true
WEBHOOK_EVENTS_MESSAGES_UPSERT=true
WEBHOOK_EVENTS_MESSAGES_UPDATE=true
WEBHOOK_EVENTS_CONNECTION_UPDATE=true

WebSocket:

WEBSOCKET_ENABLED=false
WEBSOCKET_GLOBAL_EVENTS=false

RabbitMQ:

RABBITMQ_ENABLED=false
RABBITMQ_URI=amqp://guest:guest@rabbitmq:5672
RABBITMQ_EXCHANGE_NAME=evolution
RABBITMQ_GLOBAL_ENABLED=false

Apache Kafka:

KAFKA_ENABLED=false
KAFKA_CLIENT_ID=evolution-api
KAFKA_BROKERS=kafka:9092
KAFKA_TOPIC_PREFIX=evolution

Amazon SQS:

SQS_ENABLED=false
SQS_ACCESS_KEY_ID=
SQS_SECRET_ACCESS_KEY=
SQS_ACCOUNT_ID=
SQS_REGION=us-east-1

S3 Storage (Amazon S3 or MinIO):

S3_ENABLED=false
S3_ACCESS_KEY=
S3_SECRET_KEY=
S3_BUCKET=evolution
S3_ENDPOINT=s3.amazonaws.com
S3_REGION=us-east-1
S3_USE_SSL=true

OpenAI Integration:

OPENAI_ENABLED=false

Chatwoot Integration:

CHATWOOT_ENABLED=false
CHATWOOT_MESSAGE_READ=true
CHATWOOT_MESSAGE_DELETE=true
CHATWOOT_IMPORT_DATABASE_CONNECTION_URI=

Typebot Integration:

TYPEBOT_ENABLED=false
TYPEBOT_API_VERSION=latest

Dify Integration:

DIFY_ENABLED=false

Proxy Configuration:

PROXY_HOST=
PROXY_PORT=
PROXY_PROTOCOL=http
PROXY_USERNAME=
PROXY_PASSWORD=

SSL Configuration:

SERVER_TYPE=https
SSL_CONF_PRIVKEY=/path/to/privkey.pem
SSL_CONF_FULLCHAIN=/path/to/fullchain.pem

See the .env.example file for the complete list.

Generate a secure API key: openssl rand -hex 32

Configure PostgreSQL credentials

The docker-compose.yaml expects PostgreSQL environment variables. Add these to your .env:

.env

# PostgreSQL Configuration
POSTGRES_DATABASE=evolution_db
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=your-secure-password-here

Update your database connection URI to match:

.env

DATABASE_CONNECTION_URI='postgresql://postgres:your-secure-password-here@evolution-postgres:5432/evolution_db?schema=evolution_api'

Start the services

Launch all services with Docker Compose:

docker-compose up -d

This creates and starts:

evolution_api - Main API server (port 8080)
evolution_frontend - Management interface (port 3000)
evolution_postgres - PostgreSQL database (port 5432)
evolution_redis - Redis cache (port 6379)

Verify all services are running:

docker-compose ps

You should see all containers in “Up” status.

Verify the installation

Check if the API is responding:

curl http://localhost:8080

Access the Evolution Manager interface at:

http://localhost:3000

View API logs:

docker-compose logs -f api

Docker Compose services

The default docker-compose.yaml includes:

version: "3.8"

services:
  api:
    container_name: evolution_api
    image: evoapicloud/evolution-api:latest
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - evolution_instances:/evolution/instances
    env_file:
      - .env
    depends_on:
      - redis
      - evolution-postgres

  frontend:
    container_name: evolution_frontend
    image: evoapicloud/evolution-manager:latest
    restart: always
    ports:
      - "3000:80"

  redis:
    container_name: evolution_redis
    image: redis:latest
    restart: always
    ports:
      - "6379:6379"
    volumes:
      - evolution_redis:/data

  evolution-postgres:
    container_name: evolution_postgres
    image: postgres:15
    restart: always
    environment:
      - POSTGRES_DB=${POSTGRES_DATABASE}
      - POSTGRES_USER=${POSTGRES_USERNAME}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  evolution_instances:
  evolution_redis:
  postgres_data:

The Evolution API Docker image is based on node:24-alpine and includes ffmpeg for media processing.

Manual installation (npm)

For development or custom deployments, you can install Evolution API manually using npm.

Prerequisites

Install Node.js

Evolution API requires Node.js 20 or higher. We recommend using nvm:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Install Node.js 20
nvm install 20
nvm use 20

# Verify installation
node --version
npm --version

Install system dependencies

Install required system packages:Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y git ffmpeg wget curl

macOS:

brew install git ffmpeg wget curl

CentOS/RHEL:

sudo yum install -y git ffmpeg wget curl

Install PostgreSQL

Install and configure PostgreSQL:Ubuntu/Debian:

sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

macOS:

brew install postgresql@15
brew services start postgresql@15

Create the database:

sudo -u postgres psql

CREATE DATABASE evolution_db;
CREATE USER evolution_user WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE evolution_db TO evolution_user;
\q

Install Redis

Install and start Redis:Ubuntu/Debian:

sudo apt-get install redis-server
sudo systemctl start redis
sudo systemctl enable redis

macOS:

brew install redis
brew services start redis

Verify Redis is running:

redis-cli ping
# Should return: PONG

Installation steps

Clone and install

# Clone repository
git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api

# Install dependencies
npm install

Configure environment

Copy and edit the environment file:

cp .env.example .env

Update the database connection for your local setup:

.env

DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI='postgresql://evolution_user:your-secure-password@localhost:5432/evolution_db?schema=evolution_api'

CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://localhost:6379/6

AUTHENTICATION_API_KEY=your-secure-api-key-here
SERVER_URL=http://localhost:8080

Set database provider

Evolution API supports PostgreSQL and MySQL. Set the provider before running database commands:

export DATABASE_PROVIDER=postgresql

Or for MySQL:

export DATABASE_PROVIDER=mysql

Generate and deploy database

Generate Prisma client and run migrations:

npm run db:generate
npm run db:deploy

The db:deploy script automatically selects the correct schema based on your DATABASE_PROVIDER environment variable.

Build the project

Compile TypeScript to JavaScript:

npm run build

This creates the production build in the dist/ directory.

Start the server

For development with hot reload:

npm run dev:server

For production:

npm run start:prod

The API will be available at http://localhost:8080

Using the installation script

Evolution API includes an automated installation script for Linux and macOS:

chmod +x local_install.sh
./local_install.sh

For development mode:

./local_install.sh -dev

The script automatically:

Installs nvm and Node.js 20
Installs project dependencies
Generates and deploys the database
Starts the server

MySQL configuration

To use MySQL instead of PostgreSQL:

Install MySQL

Ubuntu/Debian:

sudo apt-get install mysql-server
sudo systemctl start mysql
sudo systemctl enable mysql

macOS:

brew install mysql
brew services start mysql

Create database

sudo mysql

CREATE DATABASE evolution_db;
CREATE USER 'evolution_user'@'localhost' IDENTIFIED BY 'your-secure-password';
GRANT ALL PRIVILEGES ON evolution_db.* TO 'evolution_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Update environment

.env

DATABASE_PROVIDER=mysql
DATABASE_CONNECTION_URI='mysql://evolution_user:your-secure-password@localhost:3306/evolution_db'

Deploy database

export DATABASE_PROVIDER=mysql
npm run db:generate
npm run db:deploy

Production deployment

For production environments, consider these additional configurations:

Using process managers

PM2
systemd

Install and configure PM2:

npm install -g pm2

# Start Evolution API
pm2 start npm --name "evolution-api" -- run start:prod

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup

Monitor your application:

pm2 status
pm2 logs evolution-api
pm2 monit

Create a systemd service file:

/etc/systemd/system/evolution-api.service

[Unit]
Description=Evolution API
After=network.target postgresql.service redis.service

[Service]
Type=simple
User=evolution
WorkingDirectory=/opt/evolution-api
Environment="NODE_ENV=production"
Environment="DATABASE_PROVIDER=postgresql"
ExecStart=/usr/bin/npm run start:prod
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable evolution-api
sudo systemctl start evolution-api
sudo systemctl status evolution-api

SSL/HTTPS configuration

To enable HTTPS, update your .env:

.env

SERVER_TYPE=https
SSL_CONF_PRIVKEY=/path/to/privkey.pem
SSL_CONF_FULLCHAIN=/path/to/fullchain.pem

Use Let’s Encrypt with Certbot to obtain free SSL certificates.

Reverse proxy with Nginx

Example Nginx configuration:

/etc/nginx/sites-available/evolution-api

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/evolution-api /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Environment-specific settings

Production environment variables

Security:

AUTHENTICATION_API_KEY=<generated-secure-key>
CORS_ORIGIN=https://yourdomain.com

Performance:

CACHE_REDIS_ENABLED=true
CACHE_REDIS_SAVE_INSTANCES=true
DATABASE_SAVE_DATA_INSTANCE=true

Logging:

LOG_LEVEL=ERROR,WARN,INFO
LOG_COLOR=false

Monitoring:

PROMETHEUS_METRICS=true
METRICS_AUTH_REQUIRED=true
METRICS_USER=prometheus
METRICS_PASSWORD=<secure-password>
SENTRY_DSN=<your-sentry-dsn>

Database migrations

When updating Evolution API, you may need to run database migrations:

# Set your database provider
export DATABASE_PROVIDER=postgresql

# Run migrations
npm run db:deploy

For development (creating new migrations):

npm run db:migrate:dev

Always backup your database before running migrations in production.

Troubleshooting

Docker container fails to start

Check container logs:

docker-compose logs api
docker-compose logs evolution-postgres
docker-compose logs redis

Common issues:

Port conflicts: Check if ports 8080, 3000, 5432, or 6379 are already in use
Missing environment variables: Verify all required variables are set in .env
Database connection: Ensure PostgreSQL credentials match in both .env and docker-compose.yaml

Database connection errors

Verify database is accessible:

# For Docker
docker-compose exec evolution-postgres pg_isready

# For manual installation
psql -h localhost -U evolution_user -d evolution_db

Check connection URI format:

PostgreSQL: postgresql://user:pass@host:5432/database?schema=public
MySQL: mysql://user:pass@host:3306/database

Redis connection errors

Test Redis connection:

# For Docker
docker-compose exec redis redis-cli ping

# For manual installation
redis-cli ping

Verify Redis URI in .env:

CACHE_REDIS_URI=redis://localhost:6379/6

Build failures

If npm run build fails:

Clear node modules and reinstall:

rm -rf node_modules package-lock.json
npm install

Verify Node.js version:

node --version
# Should be v20.x.x or higher

Check TypeScript compilation:
npx tsc --noEmit

Port already in use

Change the default port in .env:

SERVER_PORT=3333
SERVER_URL=http://localhost:3333

For Docker, update docker-compose.yaml:

ports:
  - "3333:8080"

Next steps

Now that Evolution API is installed, you can:

Create your first instance

Follow the quickstart guide to create a WhatsApp instance

Configure webhooks

Set up webhooks to receive real-time events

Explore integrations

Connect with Typebot, Chatwoot, OpenAI, and more

API documentation

Explore all available endpoints and features

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

Overview

Docker installation (recommended)

Prerequisites

Installation steps

Docker Compose services

Manual installation (npm)

Prerequisites

Installation steps

Using the installation script

MySQL configuration

Production deployment

Using process managers

SSL/HTTPS configuration

Reverse proxy with Nginx

Environment-specific settings

Database migrations

Troubleshooting

Next steps

Create your first instance

Configure webhooks

Explore integrations

API documentation

​Overview

​Docker installation (recommended)

​Prerequisites

​Installation steps

​Docker Compose services

​Manual installation (npm)

​Prerequisites

​Installation steps

​Using the installation script

​MySQL configuration

​Production deployment

​Using process managers

​SSL/HTTPS configuration

​Reverse proxy with Nginx

​Environment-specific settings

​Database migrations

​Troubleshooting

​Next steps

Create your first instance

Configure webhooks

Explore integrations

API documentation

Overview

Docker installation (recommended)

Prerequisites

Installation steps

Docker Compose services

Manual installation (npm)

Prerequisites

Installation steps

Using the installation script

MySQL configuration

Production deployment

Using process managers

SSL/HTTPS configuration

Reverse proxy with Nginx

Environment-specific settings

Database migrations

Troubleshooting

Next steps