MinIO Storage

MinIO is a high-performance, S3-compatible object storage system that you can self-host. It’s an excellent alternative to Amazon S3 for organizations that want full control over their data storage.

Overview

MinIO provides:

S3-compatible API (works with Evolution API’s S3 integration)
Self-hosted deployment (full data sovereignty)
High performance and scalability
Simple installation and configuration
SSL/TLS support for secure connections

Installation

Docker Deployment

The easiest way to deploy MinIO is using Docker:

Create MinIO directories

Create directories for MinIO data and configuration:

mkdir -p ~/minio/data
mkdir -p ~/minio/config

Run MinIO container

Start MinIO using Docker:

docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin123 \
  -v ~/minio/data:/data \
  minio/minio server /data --console-address ":9001"

Access MinIO Console

Open your browser and navigate to http://localhost:9001 to access the MinIO web console.Login with:

Username: minioadmin
Password: minioadmin123

Create a bucket

In the MinIO console, create a new bucket named evolution for storing Evolution API media files.

Create access credentials

Generate access keys in the MinIO console:

Go to “Access Keys” in the left sidebar
Click “Create access key”
Save the Access Key and Secret Key

Docker Compose Deployment

For production deployments, use Docker Compose:

docker-compose.yaml

version: '3.8'

services:
  minio:
    image: minio/minio:latest
    container_name: evolution_minio
    restart: always
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: your_secure_password_here
    volumes:
      - minio_data:/data
    command: server /data --console-address ":9001"
    networks:
      - evolution-net
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

volumes:
  minio_data:

networks:
  evolution-net:
    driver: bridge

Start the service:

docker-compose up -d

Evolution API Configuration

Basic Configuration

Configure Evolution API to use MinIO by setting these environment variables:

.env

# MinIO Storage Configuration
S3_ENABLED=true
S3_ACCESS_KEY=your_minio_access_key
S3_SECRET_KEY=your_minio_secret_key
S3_BUCKET=evolution
S3_ENDPOINT=localhost:9000
S3_USE_SSL=false
S3_REGION=us-east-1
S3_PORT=9000

SSL/TLS Configuration

For production deployments, enable SSL/TLS on MinIO:

Generate SSL certificates

Create SSL certificates for MinIO:

# Using Let's Encrypt (recommended for production)
certbot certonly --standalone -d minio.yourdomain.com

# Or generate self-signed certificates (development only)
openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 \
  -subj "/C=US/ST=State/L=City/O=Organization/CN=minio.yourdomain.com" \
  -keyout minio.key -out minio.crt

Configure MinIO with certificates

Create the certificate directory and add your certificates:

mkdir -p ~/minio/config/certs
cp minio.crt ~/minio/config/certs/public.crt
cp minio.key ~/minio/config/certs/private.key

Update Docker Compose configuration

Mount the certificates directory:

volumes:
  - minio_data:/data
  - ~/minio/config/certs:/root/.minio/certs

Update Evolution API configuration

Enable SSL in your Evolution API configuration:

S3_ENABLED=true
S3_ACCESS_KEY=your_minio_access_key
S3_SECRET_KEY=your_minio_secret_key
S3_BUCKET=evolution
S3_ENDPOINT=minio.yourdomain.com
S3_USE_SSL=true
S3_REGION=us-east-1
S3_PORT=443

Environment Variables

Required Variables

boolean

required

Enable S3 storage integration.

S3_ENABLED=true

string

required

MinIO access key ID created in the MinIO console.

S3_ACCESS_KEY=your_minio_access_key

string

required

MinIO secret key corresponding to the access key.

S3_SECRET_KEY=your_minio_secret_key

string

required

The name of the MinIO bucket for storing media files.

S3_BUCKET=evolution

string

required

MinIO server endpoint URL (without http:// or https://).Examples:

Local: localhost:9000
Domain: minio.yourdomain.com
IP: 192.168.1.100:9000

S3_ENDPOINT=minio.yourdomain.com

Optional Variables

boolean

Enable SSL/TLS for secure connections to MinIO.Default: true

S3_USE_SSL=true

number

The port MinIO is running on.Default: 443 (with SSL) or 9000 (without SSL)

S3_PORT=9000

string

MinIO region identifier. MinIO uses us-east-1 by default.Default: us-east-1

S3_REGION=us-east-1

Configuration Examples

# MinIO running on localhost without SSL
S3_ENABLED=true
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin123
S3_BUCKET=evolution
S3_ENDPOINT=localhost:9000
S3_USE_SSL=false
S3_REGION=us-east-1
S3_PORT=9000

# MinIO with SSL/TLS enabled
S3_ENABLED=true
S3_ACCESS_KEY=prod_access_key_id
S3_SECRET_KEY=prod_secret_access_key
S3_BUCKET=evolution
S3_ENDPOINT=minio.yourdomain.com
S3_USE_SSL=true
S3_REGION=us-east-1
S3_PORT=443

# MinIO and Evolution API in same Docker network
S3_ENABLED=true
S3_ACCESS_KEY=evolution_minio_key
S3_SECRET_KEY=evolution_minio_secret
S3_BUCKET=evolution
S3_ENDPOINT=evolution_minio:9000
S3_USE_SSL=false
S3_REGION=us-east-1
S3_PORT=9000

# MinIO on separate server with IP address
S3_ENABLED=true
S3_ACCESS_KEY=remote_access_key
S3_SECRET_KEY=remote_secret_key
S3_BUCKET=evolution
S3_ENDPOINT=192.168.1.100:9000
S3_USE_SSL=false
S3_REGION=us-east-1
S3_PORT=9000

Complete Docker Compose Setup

Here’s a complete docker-compose.yaml with Evolution API and MinIO:

docker-compose.yaml

version: '3.8'

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

  minio:
    image: minio/minio:latest
    container_name: evolution_minio
    restart: always
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    volumes:
      - minio_data:/data
    command: server /data --console-address ":9001"
    networks:
      - evolution-net
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

  redis:
    container_name: evolution_redis
    image: redis:latest
    restart: always
    command: redis-server --port 6379 --appendonly yes
    volumes:
      - evolution_redis:/data
    networks:
      - evolution-net

  postgres:
    container_name: evolution_postgres
    image: postgres:15
    restart: always
    environment:
      POSTGRES_DB: evolution_db
      POSTGRES_USER: evolution
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - evolution-net

volumes:
  evolution_instances:
  evolution_redis:
  postgres_data:
  minio_data:

networks:
  evolution-net:
    driver: bridge

Corresponding .env file:

.env

# MinIO Storage
S3_ENABLED=true
S3_ACCESS_KEY=your_minio_access_key
S3_SECRET_KEY=your_minio_secret_key
S3_BUCKET=evolution
S3_ENDPOINT=evolution_minio:9000
S3_USE_SSL=false
S3_REGION=us-east-1
S3_PORT=9000

# MinIO Root Password
MINIO_ROOT_PASSWORD=your_secure_password_here

# Database
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://evolution:${POSTGRES_PASSWORD}@postgres:5432/evolution_db?schema=evolution_api

# PostgreSQL Password
POSTGRES_PASSWORD=your_postgres_password_here

# Redis Cache
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://evolution_redis:6379/6

Bucket Configuration

Access Policy

Set appropriate access policies for your MinIO bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": ["*"]
      },
      "Action": [
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::evolution/*"
      ]
    }
  ]
}

Only make objects publicly accessible if necessary. Evolution API can work with private buckets using signed URLs.

Versioning

Enable versioning to protect against accidental deletions:

mc version enable myminio/evolution

Lifecycle Rules

Set up lifecycle rules to manage storage:

{
  "Rules": [
    {
      "ID": "DeleteOldVersions",
      "Status": "Enabled",
      "Expiration": {
        "Days": 30
      },
      "NoncurrentVersionExpiration": {
        "NoncurrentDays": 7
      }
    }
  ]
}

Monitoring and Management

MinIO Console

Access the MinIO console at http://your-server:9001 to:

Monitor bucket usage and statistics
Manage access keys and users
Configure bucket policies and lifecycle rules
Browse and download files
View server health and performance metrics

Using MinIO Client (mc)

Install and configure the MinIO client for command-line management:

# Install MinIO client
wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc
sudo mv mc /usr/local/bin/

# Configure alias
mc alias set myminio http://localhost:9000 minioadmin minioadmin123

# List buckets
mc ls myminio

# List objects in bucket
mc ls myminio/evolution

# Get bucket statistics
mc admin info myminio

Troubleshooting

Connection refused errors

If Evolution API cannot connect to MinIO:

Verify MinIO is running: docker ps | grep minio
Check that the endpoint is accessible: curl http://localhost:9000/minio/health/live
If using Docker networks, ensure both containers are on the same network
Verify firewall rules allow traffic on port 9000

Access denied errors

If you receive access denied errors:

Verify the access key and secret key are correct
Check bucket permissions in the MinIO console
Ensure the bucket exists: mc ls myminio/evolution
Verify the MinIO user has read/write permissions on the bucket

SSL certificate errors

For SSL/TLS issues:

Verify certificates are correctly mounted in the Docker container
Check certificate file permissions: chmod 644 public.crt and chmod 600 private.key
Ensure certificate paths are correct: /root/.minio/certs/
For self-signed certificates, you may need to add them to your system’s trust store

Performance issues

To improve MinIO performance:

Use SSD storage for the data volume
Increase Docker memory allocation if running locally
Enable erasure coding for large deployments
Use MinIO’s distributed mode for high availability
Monitor disk I/O and network bandwidth

High Availability Setup

For production deployments, consider MinIO’s distributed mode:

docker run -d \
  --name minio1 \
  -p 9000:9000 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin123 \
  minio/minio server \
  http://minio{1...4}/data{1...2}

Distributed MinIO requires at least 4 drives across multiple servers for high availability.

Security Best Practices

Change default credentials - Never use minioadmin/minioadmin123 in production
Enable SSL/TLS - Always use HTTPS for production deployments
Use strong passwords - Generate secure passwords for root and access keys
Restrict network access - Use firewall rules to limit access to MinIO ports
Regular backups - Implement backup strategies for MinIO data
Monitor access logs - Enable and review MinIO audit logs
Update regularly - Keep MinIO updated to the latest stable version

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

Overview

Installation

Docker Deployment

Docker Compose Deployment

Evolution API Configuration

Basic Configuration

SSL/TLS Configuration

Environment Variables

Required Variables

Optional Variables

Configuration Examples

Complete Docker Compose Setup

Bucket Configuration

Access Policy

Versioning

Lifecycle Rules

Monitoring and Management

MinIO Console

Using MinIO Client (mc)

Troubleshooting

High Availability Setup

Security Best Practices

Next Steps

Amazon S3

Docker Deployment

​Overview

​Installation

​Docker Deployment

​Docker Compose Deployment

​Evolution API Configuration

​Basic Configuration

​SSL/TLS Configuration

​Environment Variables

​Required Variables

​Optional Variables

​Configuration Examples

​Complete Docker Compose Setup

​Bucket Configuration

​Access Policy

​Versioning

​Lifecycle Rules

​Monitoring and Management

​MinIO Console

​Using MinIO Client (mc)

​Troubleshooting

​High Availability Setup

​Security Best Practices

​Next Steps

Amazon S3

Docker Deployment

Overview

Installation

Docker Deployment

Docker Compose Deployment

Evolution API Configuration

Basic Configuration

SSL/TLS Configuration

Environment Variables

Required Variables

Optional Variables

Configuration Examples

Complete Docker Compose Setup

Bucket Configuration

Access Policy

Versioning

Lifecycle Rules

Monitoring and Management

MinIO Console

Using MinIO Client (mc)

Troubleshooting

High Availability Setup

Security Best Practices

Next Steps