Objectiu

Evolution API és un gateway que exposa una API REST per connectar WhatsApp i enviar/rebre missatges des del teu codi. Normalment el vull córrer dins d’un contenidor Docker, però primer necessito una VM on allotjar-lo.

Aquest article explica com:

  • crear una VM Debian a Proxmox amb cloud-init
  • instal·lar Docker i docker-compose automàticament
  • desplegar Evolution API amb Redis i PostgreSQL via docker-compose.yml
  • entendre per què el cat <<EOF i cat <<'EOF' no són intercanviables en scripts bash

Tot en un únic script, reutilitzable i modificable.

Proxmox: la VM base des de terminal

Proxmox té una eina CLI molt potent anomenada qm. Amb quatre ordres en un script tens una VM funcional. La recepta bàsica és:

VMID=903
VMNAME="evolution-v2"
RAM=4096
CORES=2
DISK_SIZE=20G
BRIDGE="vmbr0"
IP_FIXA="192.168.74.7/24"
GW="192.168.74.1"
STORAGE="local-lvm"

Descarregar la imatge base Debian Cloud i crear la VM:

# 1. Preparar imatge
wget https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2

# 2. Crear VM buida
qm destroy $VMID 2>/dev/null
qm create $VMID --name $VMNAME --memory $RAM --cores $CORES --net0 virtio,bridge=$BRIDGE

# 3. Configurar hardware
qm set $VMID --scsihw virtio-scsi-pci --serial0 socket --vga serial0

# 4. Importar disc i expandir
qm importdisk $VMID debian-12-genericcloud-amd64.qcow2 $STORAGE
qm set $VMID --virtio0 $STORAGE:vm-$VMID-disk-0
qm resize $VMID virtio0 20G

# 5. Cloud-init + xarxa
qm set $VMID --ide2 $STORAGE:cloudinit
qm set $VMID --boot c --bootdisk virtio0
qm set $VMID --cicustom "user=local:snippets/angel-cloudinit.yaml"
qm set $VMID --ipconfig0 "ip=$IP_FIXA,gw=$GW"

# 6. Arrencar
qm start $VMID

Aquest procés és completament reproduïble: canvies VMID, IP_FIXA i llences.

La màgia del snippet cloud-init

El fitxer angel-cloudinit.yaml es guarda a /var/lib/vz/snippets/ de Proxmox. Aquí hi poses tot el que ha de passar dins la VM en el primer arrencada.

L’script original fa servir dos patrons de cat:

cat <<EOF — expansió activada

Quan escrius:

cat <<EOF > fitxer
Hola $NAME
EOF

El shell substitueix $NAME pel valor de la variable. Això és perfecte per a paràmetres que has de resoldre en temps de creació del snippet (com la IP fixa, el nom de la VM, etc.).

cat <<'EOF' — expansió desactivada (literal)

Quan el delimitador va entre cometes simples:

cat <<'EOF' > fitxer
Hola $NAME
EOF

El contingut es queda literal: escriu $NAME sense interpretar-lo. Això és imprescindible per a fitxers de configuració que han de contenir variables pròpies, com un .env de Docker que ja es resoldrà dins del contenidor.

La regla d’or

  1. cat <<EOF → el shell substitueix tot ($VAR, $(command), $HOME…)
  2. cat <<'EOF' → el contingut es copia tal qual

Dominar aquesta diferència és clau quan generes fitxers de configuració dins de scripts d’automatització.

L’script combina els dos patrons

En el codi real veurem:

  • cat <<EOF per al bloc packages i runcmd directe, on es valors com $API_KEY, $VMNAME o $IP_FIXA s’han d’injectar.
  • cat <<'EOT' per al docker-compose.yml i el .env de l’Evolution API, perquè variables com ${EVOLUTION_API_PORT} o ${POSTGRESS_USER} no es resolguin a la VM sinó dins dels contenidors.

Arquitectura de l’Evolution API amb Docker

El docker-compose.yml desplega tres serveis:

Servei Imatge Funció
api evoapicloud/evolution-api:latest Gateway WhatsApp amb API REST
redis redis:latest Caché i gestió de sessions (amb persistència --appendonly yes)
postgres postgres:15 Base de dades principal de l’Evolution API

Els tres contenidors comparteixen una xarxa interna (evolution-net) i exposen els ports necessaris a l’host.

La configuració es fa a través d’un .env que es passa com a env_file al servei api.

El fitxer .env de l’Evolution API

L’Evolution API admet centenars de variables d’entorn. Les més importants per arrencar són:

AUTHENTICATION_API_KEY=la_teva_clau
EVOLUTION_API_PORT=8080
SERVER_TYPE=http
SERVER_IP=192.168.74.7

# PostgreSQL
POSTGRESS_USER=angel
POSTGRESS_PASS=contrasenya_segura
POSTGRESS_PORT=5432

# Redis
REDIS_PORT=6379

A partir d’aquí pots habilitar integracions com:

Integració Variable clau Què fa
Webhook WEBHOOK_GLOBAL_ENABLED=true Rep els events de WhatsApp a una URL externa
WebSocket WEBSOCKET_ENABLED=true Connexió en temps real
RabbitMQ RABBITMQ_ENABLED=true Cua de missatges per a sistemes empresarials
SQS SQS_ENABLED=true Integració amb AWS SQS
Chatwoot CHATWOOT_ENABLED=true CRM de codi obert per a atenció al client
Typebot TYPEBOT_ENABLED=true Chatbots visuals
OpenAI OPENAI_ENABLED=true Intel·ligència artificial als xats
Dify DIFY_ENABLED=true Plataforma de workflow amb IA
n8n N8N_ENABLED=true Automatització de workflows (com Zapier self-hosted)
EvoAI EVOAI_ENABLED=true IA nativa de l’Evolution API
Pusher PUSHER_ENABLED=true Events en temps real externalitzats

Comprovar que tot funciona

Un cop la VM arrenca i el cloud-init ha instal·lat Docker:

# Comprovar els contenidors
sudo docker ps

# Hauries de veure:
# - evolution_api
# - redis
# - postgres

# Veure logs de l'API
sudo docker logs -f evolution_api

Si tot va bé, l’Evolution API respon a http://192.168.74.7:8080.

Testejar l’API amb Postman

Un cop l’API està en marxa, pots:

  • Enviar missatges de WhatsApp
  • Llegir l’estat de la sessió
  • Regenerar el QR
  • Testejar respostes JSON
  • Veure errors i logs

Postman és ideal per validar que el backend funciona abans d’integrar-ho al teu propi codi (per exemple, a un Agent Hub com el que tinc amb l’email_digest_agent).

Possibles dubtes

Cal passar l’Evolution API a HTTPS?

Depèn de l’ús. Si només l’utilitzes dins de la teva xarxa local, HTTP és suficient. Per a producció, posa-hi un proxy invers (Nginx/Caddy) amb certificat Let’s Encrypt.

Es pot substituir iMessage per Evolution API?

Sí. Si tens un sistema macOS que enviava notificacions per iMessage, pots redirigir aquestes notificacions a un número de WhatsApp via Evolution API. L’email_digest_agent del meu Agent Hub ho fa exactament: genera un resum de correus i l’envia per WhatsApp.

Es pot prioritzar certs temes a l’email_digest_agent?

Totalment. El sistema de prompting permet definir una llista de temes prioritaris (terminis, seguretat, escola, factures…) i la resta es classifica com a “Altres temes que potser vols revisar”. Així no et perds el crític però tampoc descartes res important.

Resum

En un sol script de bash pots:

  1. Crear una VM a Proxmox amb Debian Cloud
  2. Configurar-la amb cloud-init (usuari, SSH, Docker)
  3. Desplegar Evolution API amb Redis i PostgreSQL
  4. Deixar l’API operativa

I tot amb la flexibilitat dels dos patrons de cat per gestionar correctament l’expansió de variables segons el context.

El codi font complet és a GitHub i l’script de cloud-init es pot adaptar a qualsevol entorn Proxmox canviant IP, VMID i credencials.