Install Evolution API (WhatsApp API - Baileys) with Docker Compose on Ubuntu at Proxmox VM

Posted by Monirul on

The Evolution API is a powerful tool for integrating WhatsApp messaging into your applications, enabling features like sending messages, managing groups, and handling webhooks. In this guide, I’ll walk you through setting up the Evolution API using Docker Compose on your local machine, complete with PostgreSQL and Redis for a robust deployment. We’ll use a setup tailored for a local IP (192.168.22.205), address common difficulty like database connection errors, and ensure the API runs smoothly.

Prerequisites

Before we start, ensure you have:

  • Docker and Docker Compose installed on your machine (Linux, macOS, or Windows).
  • A local IP address (e.g., 192.168.22.205 for this guide).
  • Basic knowledge of Docker and environment variables.
  • A secure API key (generate one using openssl rand -hex 16 or an online tool like api-keygen.com).
  • A strong password for PostgreSQL.

Step 1: Create the Project Directory

Create a directory for your Evolution API project:

mkdir evolution-api
cd evolution-api

Step 2: Set Up Docker Compose

Create a docker-compose.yml file to define the services: the Evolution API, PostgreSQL, and Redis. This configuration ensures the API connects to the database and cache correctly and binds to your local IP.

Download this as docker-compose.yml in your project directory.

Step 3: Configure Environment Variables

Create a .env file to store configuration settings, including your local IP (192.168.22.205), database credentials, and API key.

  • Replace your_secure_api_key_here with a secure API key (e.g., a1b2c3d4e5f6g7h8i9j0).
  • Replace your_postgres_password with a strong password (e.g., A1b2C3d4!).
  • Save this as .env in the same directory.

Important: The DATABASE_CONNECTION_URI uses postgres as the host (the service name in docker-compose.yml), not localhost, to ensure the API connects to the PostgreSQL container correctly.

You can get this sample .env file from here.

Step 4: Start the Services

Clear any existing state to avoid cached issues:

docker compose down
docker volume rm evolution_instances evolution_store evolution_redis evolution_postgres
docker image rm atendai/evolution-api:v2.1.1

Then start the services:

docker compose up -d

Step 5: Verify the Setup

  1. Check Container Status:

    docker ps

    Ensure evolution_api, evolution_redis, and evolution_postgres are running with status Up. If evolution_api shows unhealthy, proceed to troubleshooting below.

  2. Monitor Logs:

    docker compose logs -f api

    Look for successful Prisma migrations and API startup messages. You should not see errors like P1001: Can't reach database server at localhost:5432.

  3. Test the API:

    curl http://192.168.22.205:8080

    Expected response:

    {"status":200,"message":"Welcome to the Evolution API, it is working!"}

  4. Initialize WhatsApp Session:

    • Use an HTTP client (e.g., Postman) to create a WhatsApp instance:
      curl -X POST http://192.168.22.205:8080/instance/create \
  -H "Authorization: Bearer your_secure_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"instanceName": "myInstance"}'
    • Retrieve the QR code for WhatsApp authentication:
      curl http://192.168.22.205:8080/instance/qr/myInstance \
  -H "Authorization: Bearer your_secure_api_key_here"
    • Input with your WhatsApp account to connect.

Now scan the QR Code and good to go




Troubleshooting Common Issues

  1. Database Connection Error (P1001):

    • If you see Can't reach database server at localhost:5432, ensure DATABASE_CONNECTION_URI in .env uses postgres:5432, not localhost.
    • Verify the PostgreSQL container is healthy:
      docker inspect evolution_postgres --format='{{.State.Health.Status}}'
    • Test connectivity:
      docker exec -it evolution_api sh
psql -h postgres -U postgres -d evolution

  2. Unhealthy API Status:

    • If the evolution_api container shows unhealthy, it’s likely the healthcheck (curl -f http://localhost:8080) is failing.
    • Check logs for errors:
      docker compose logs api
    • Increase healthcheck timeout in docker-compose.yml:
      healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080"]
  interval: 30s
  timeout: 60s
  retries: 10
    • Restart: docker compose up -d.
    • If the issue persists, temporarily disable the healthcheck (test: ["NONE"]) and test the API manually.

  3. Port Conflicts:

    • If port 8080 is occupied:
      sudo lsof -i :8080  # Linux/Mac
netstat -aon | findstr :8080  # Windows
    • Change the port in docker-compose.yml (e.g., 8081:8080) and update SERVER_URL in .env to http://192.168.22.205:8081.

Next Steps

Once the Evolution API is running, you can:

  • Set up webhooks to capture WhatsApp group messages.
  • Integrate with tools like n8n to automate workflows.
  • Store data in databases like NocoDB or MongoDB.

Check the Evolution API documentation for advanced configurations, such as sending messages or managing groups.

Conclusion

Setting up the Evolution API with Docker Compose is straightforward with the right configuration. By using the provided docker-compose.yml and .env files, you can deploy a robust WhatsApp integration on your local network (e.g., 192.168.22.205:8080). If you run into issues, the troubleshooting steps above should help you resolve them quickly. Share your experiences or questions in the comments below!

Comments

Post a Comment