Configuration

This document provides detailed information about configuring Evolution API on Dokku.

Environment Variables
Database Configuration
Authentication Configuration
Storage Configuration
Domain and Port Configuration
Advanced Configuration

Environment Variables

Required Variables

These variables are required for Evolution API to function:

Variable	Description	Example
`DATABASE_CONNECTION_URI`	PostgreSQL connection string	`postgresql://user:pass@host:5432/db`
`SERVER_URL`	Public URL of your Evolution API instance	`https://evo.example.com`
`AUTHENTICATION_API_KEY`	Global API key for authentication	`oXZkh4B2FETGL31VeOzl6gqsdav9wmC0`

Set required variables:

dokku config:set evo DATABASE_CONNECTION_URI="$(dokku config:get evo DATABASE_URL)"
dokku config:set evo SERVER_URL="https://evo.example.com"
dokku config:set evo AUTHENTICATION_API_KEY="your-secure-api-key"

Optional Variables

Customize Evolution API behavior with these optional variables:

Database Options

Variable	Description	Default
`DATABASE_SAVE_DATA_INSTANCE`	Save instance data	`true`
`DATABASE_SAVE_DATA_NEW_MESSAGE`	Save new messages	`true`
`DATABASE_SAVE_MESSAGE_UPDATE`	Save message updates	`true`
`DATABASE_SAVE_DATA_CONTACTS`	Save contact information	`true`
`DATABASE_SAVE_DATA_CHATS`	Save chat information	`true`
`DATABASE_SAVE_DATA_HISTORIC`	Save message history	`true`
`DATABASE_SAVE_DATA_LABELS`	Save message labels	`false`

Example - Minimize database usage:

dokku config:set evo DATABASE_SAVE_DATA_HISTORIC=false
dokku config:set evo DATABASE_SAVE_DATA_LABELS=false
dokku config:set evo DATABASE_SAVE_MESSAGE_UPDATE=false

Cache Options (Redis) - OPTIONAL

Note: Redis is NOT required for basic operation. Only consider enabling Redis for teams with 50+ users experiencing performance issues. See Redis Integration Guide for complete setup instructions.

Variable	Description	Default
`CACHE_REDIS_ENABLED`	Enable Redis caching	`false`
`CACHE_REDIS_URI`	Redis connection URI	-
`CACHE_REDIS_PREFIX_KEY`	Redis key prefix	`evo`

Example - Enable Redis (only if Redis is installed):

# First, install and link Redis (see redis-integration.md)
# Then configure:
dokku config:set evo CACHE_REDIS_ENABLED=true
dokku config:set evo CACHE_REDIS_URI="$(dokku config:get evo REDIS_URL)"

Webhook Configuration

Variable	Description	Default
`WEBHOOK_GLOBAL_ENABLED`	Enable global webhook	`false`
`WEBHOOK_GLOBAL_URL`	Global webhook URL	-
`WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS`	Filter events	`false`

Example - Configure webhook:

dokku config:set evo WEBHOOK_GLOBAL_ENABLED=true
dokku config:set evo WEBHOOK_GLOBAL_URL="https://your-webhook.com/endpoint"

WebSocket Configuration

Variable	Description	Default
`WEBSOCKET_ENABLED`	Enable WebSocket	`false`
`WEBSOCKET_GLOBAL_EVENTS`	Enable global events	`false`

Example - Enable WebSocket:

dokku config:set evo WEBSOCKET_ENABLED=true
dokku config:set evo WEBSOCKET_GLOBAL_EVENTS=true

Authentication Options

Variable	Description	Default
`AUTHENTICATION_TYPE`	Authentication type (`apikey` or `jwt`)	`apikey`
`AUTHENTICATION_JWT_EXPIRIN_IN`	JWT expiration time (seconds)	`3600`
`AUTHENTICATION_JWT_SECRET`	JWT secret key	-

Instance Management

Variable	Description	Default
`DEL_INSTANCE`	Auto-delete inactive instances (days)	`false`
`CLEAN_STORE_CLEANING_INTERVAL`	Storage cleanup interval (seconds)	`7200`
`CLEAN_STORE_MESSAGES`	Clean old messages	`true`
`CLEAN_STORE_MESSAGE_UP_TO`	Keep messages for (days)	`15`
`CLEAN_STORE_CHATS`	Clean old chats	`true`
`CLEAN_STORE_CONTACTS`	Clean old contacts	`true`

Language and Logging

Variable	Description	Default
`LOG_LEVEL`	Logging level	`ERROR`
`LOG_COLOR`	Colorize logs	`true`
`LANGUAGE`	API language	`en`

Available log levels: ERROR, WARN, INFO, DEBUG, VERBOSE

Database Configuration

View Current Configuration

dokku config evo | grep DATABASE

PostgreSQL Information

# View PostgreSQL service info
dokku postgres:info evo

# Check database size
dokku postgres:connect evo -c "SELECT pg_size_pretty(pg_database_size('evo'));"

Backup and Restore

Create backup:

# Linux/macOS
dokku postgres:backup evo backup-$(date +%Y%m%d)

# Windows (PowerShell)
$date = Get-Date -Format "yyyyMMdd"
ssh your-server "postgres:backup evo backup-$date"

List backups:

dokku postgres:backup-list evo

Restore from backup:

dokku postgres:backup-restore evo backup-name

Export database:

dokku postgres:export evo > evolution-backup.sql

Import database:

dokku postgres:import evo < evolution-backup.sql

Authentication Configuration

Generate Secure API Key

Linux/macOS:

API_KEY=$(openssl rand -hex 16)
dokku config:set evo AUTHENTICATION_API_KEY="$API_KEY"
echo "Your API Key: $API_KEY"

Windows (PowerShell):

$API_KEY = -join ((48..57) + (65..90) + (97..122) | Get-Random -Count 32 | ForEach-Object {[char]$_})
ssh your-server "config:set evo AUTHENTICATION_API_KEY=$API_KEY"
Write-Host "Your API Key: $API_KEY"

View Current API Key

dokku config:get evo AUTHENTICATION_API_KEY

Change API Key

dokku config:set evo AUTHENTICATION_API_KEY="new-secure-api-key"

Use JWT Authentication

dokku config:set evo AUTHENTICATION_TYPE="jwt"
dokku config:set evo AUTHENTICATION_JWT_SECRET="your-jwt-secret"
dokku config:set evo AUTHENTICATION_JWT_EXPIRIN_IN="86400"  # 24 hours

Storage Configuration

View Storage Configuration

dokku storage:report evo

Mount Additional Storage

# Mount media storage
dokku storage:mount evo /var/lib/dokku/data/storage/evo-media:/evolution/media

# Mount logs
dokku storage:mount evo /var/lib/dokku/data/storage/evo-logs:/evolution/logs

Unmount Storage

dokku storage:unmount evo /var/lib/dokku/data/storage/evo:/evolution/instances

Check Storage Usage

# Check disk usage
du -sh /var/lib/dokku/data/storage/evo

# Detailed breakdown
du -h --max-depth=1 /var/lib/dokku/data/storage/evo

Domain and Port Configuration

Configure Domain

Set primary domain:

dokku domains:set evo evo.example.com

Add additional domains:

dokku domains:add evo www.evo.example.com
dokku domains:add evo api.example.com

Remove domain:

dokku domains:remove evo www.evo.example.com

List domains:

dokku domains:report evo

Configure Ports

Set HTTP port:

dokku ports:set evo http:80:8080

Add HTTPS port:

dokku ports:add evo https:443:8080

Remove port:

dokku ports:remove evo http:80:8080

List ports:

dokku ports:report evo

SSL/TLS Configuration

Enable Let's Encrypt:

dokku letsencrypt:set evo email your@email.com
dokku letsencrypt:enable evo

Renew certificate manually:

dokku letsencrypt:renew evo

Auto-renew setup:

dokku letsencrypt:cron-job --add

View certificate info:

dokku letsencrypt:list

Advanced Configuration

Resource Limits

Set memory and CPU limits:

dokku resource:limit evo --memory 512m --cpu 1

Remove limits:

dokku resource:limit-clear evo --process-type web

View current limits:

dokku resource:report evo

Health Checks

Evolution API includes built-in health checks. View status:

dokku checks:report evo

Disable health checks (not recommended):

dokku checks:disable evo

Re-enable health checks:

dokku checks:enable evo

Proxy Configuration

Disable proxy (if using external reverse proxy):

dokku proxy:disable evo

Re-enable proxy:

dokku proxy:enable evo

Set proxy type:

dokku proxy:set evo nginx  # or 'caddy'

Network Configuration

Create custom network:

dokku network:create custom-network

Attach application to network:

dokku network:set evo attach-post-create custom-network

Detach from network:

dokku network:set evo detach-post-create custom-network

Scheduled Tasks (Cron)

Set up cron jobs:

# Create a cron script
dokku enter evo web
echo '0 2 * * * /app/cleanup.sh' | crontab -

Environment Groups

Create environment group:

# Useful for managing multiple instances
dokku config:set --no-restart evo-prod ENV=production
dokku config:set --no-restart evo-dev ENV=development

View All Configuration

# View all environment variables
dokku config evo

# Export configuration
dokku config:export evo > evo-config.env

# Import configuration
dokku config:bundle evo < evo-config.env

Configuration Best Practices

Security

Use strong API keys (minimum 32 characters)
Enable HTTPS with Let's Encrypt
Rotate API keys periodically
Use environment variables for sensitive data
Disable unnecessary features to reduce attack surface

Performance

Enable Redis for 50+ users
Disable message history if not needed
Set appropriate resource limits
Monitor and adjust based on usage

Reliability

Set up automated backups
Enable health checks
Configure log retention
Monitor disk usage
Use persistent storage

Development vs Production

Development:

dokku config:set evo LOG_LEVEL=DEBUG
dokku config:set evo DEL_INSTANCE=1  # Delete after 1 day

Production:

dokku config:set evo LOG_LEVEL=ERROR
dokku config:set evo DEL_INSTANCE=false
dokku config:set evo DATABASE_SAVE_DATA_HISTORIC=true

Next Steps

Performance & Optimization - Optimize your deployment
Useful Commands - Common management tasks
System Requirements - Hardware recommendations

Uh oh!

FilesExpand file tree

configuration.md

Latest commit

History