Instalar OpenWA en Windows, Corregir npm 11 y Desplegar en VPS

Aprende a instalar OpenWA en Windows, solucionar los fallos de compatibilidad con npm 11 y desplegar un gateway de WhatsApp automatizado en un VPS Ubuntu utilizando Docker, Nginx y SSL. OpenWA es una de las librerías más potentes del ecosistema open source para control de sesiones de mensajería mediante una API REST y un dashboard web integrado.

📐 1. Arquitectura de Despliegue de OpenWA

Al instalar OpenWA en Windows para desarrollo y posteriormente desplegarlo en producción, utilizaremos una topología segura basada en proxy inverso que aísla la API REST y el dashboard tras Nginx con HTTPS:

Tráfico Público (Internet)
       │
       ├── HTTPS :443 / HTTP :80
       ▼
 [ Nginx + Certbot ]
       │
       ├── Proxy Interno (WebSocket / HTTP)
       ▼
 [ Contenedor Docker OpenWA ] ⚡ 127.0.0.1:2785
       ├── Node.js 22 (NestJS API + Dashboard React)
       ├── Motor WhatsApp (whatsapp-web.js / Headless Chromium)
       └── Persistencia (Volumen SQLite + Media)

💻 2. Instalación Local en Windows 11

Comienza clonando el repositorio oficial en tu entorno local. Si te interesa optimizar tu entorno de desarrollo, recuerda que también puedes revisar nuestra guía para instalar OmniRoute, OpenCode y Cline en VS Code.

# 1. Navega a tu directorio de proyectos
Set-Location C:\proyectos

# 2. Clona el repositorio oficial de OpenWA
git clone https://github.com/rmyndharis/OpenWA.git
Set-Location .\OpenWA

# 3. Verifica la versión y la rama activa
git status

🛠️ 3. Corrección del Error EALLOWSCRIPTS en npm 11

Al intentar ejecutar npm ci en entornos con npm 11, la variable exportada npm_config_allow_scripts=true se propaga a la instalación anidada del subdirectorio dashboard, bloqueando la compilación con el error EALLOWSCRIPTS: --allow-scripts is not allowed in project-scoped installs.

# Paso A: Instalar dependencias raíz omitiendo scripts
npm ci --ignore-scripts

# Paso B: Instalar el dashboard manualmente
Push-Location .\dashboard
npm ci
Pop-Location

# Paso C: Aplicar parches requeridos para whatsapp-web.js
node .\scripts\patch-wwebjs-201832.js --best-effort
node .\scripts\patch-wwebjs-newsletter-preview.js --best-effort

🚀 4. Configuración y Arranque en Desarrollo

Copia el archivo de variables de entorno mínimas e inicia el servidor:

Copy-Item .\.env.minimal .\.env
npm run dev

El sistema levantará la API REST en http://localhost:2785/api y el Dashboard en http://localhost:2886. Obtén la clave administrativa inicial generada automáticamente:

Get-Content .\data\.api-key

☁️ 5. Despliegue en VPS Ubuntu con Docker

Para el entorno de producción en Ubuntu 24.04 LTS (Hostinger KVM / VPS), preparamos la memoria SWAP de 2GB para evitar cuellos de botella en Chromium e instalamos las herramientas base. Si además trabajas con procesamiento inteligente de comandos de voz en tus aplicaciones, te recomendamos consultar cómo instalar OpenCluely con reconocimiento de voz local.

# 1. Crear memoria Swap de respaldo (2GB)
fallocate -l 2G /swapfile-openwa
chmod 600 /swapfile-openwa
mkswap /swapfile-openwa
swapon /swapfile-openwa
echo '/swapfile-openwa none swap sw 0 0' >> /etc/fstab

# 2. Instalar Docker, Nginx y Certbot
export DEBIAN_FRONTEND=noninteractive
apt-get update && apt-get install -y docker.io docker-compose-v2 nginx certbot python3-certbot-nginx ufw
systemctl enable --now docker nginx

Clona el repositorio en /opt/openwa y configura las variables de entorno para producción:

git clone --branch fix/postinstall-allow-scripts-env https://github.com/configurowebmax/OpenWA.git /opt/openwa
cd /opt/openwa
cp .env.minimal .env

# Inyectar variables críticas de producción
cat >> /opt/openwa/.env <<'EOF'
NODE_ENV=production
AUTO_START_SESSIONS=true
TRUSTED_PROXIES=127.0.0.1,172.16.0.0/12
OPENWA_MEM_LIMIT=3g
WWEBJS_AUTH_TIMEOUT_MS=60000
ENABLE_SWAGGER=false
EOF

# Generar y proteger Master API Key
OPENWA_KEY="$(openssl rand -hex 32)"
printf 'API_MASTER_KEY=%s\n' "$OPENWA_KEY" >> /opt/openwa/.env
printf '%s\n' "$OPENWA_KEY" > /root/openwa-master-key.txt
chmod 600 /opt/openwa/.env /root/openwa-master-key.txt

Construye la imagen Docker y despliega el contenedor aislado:

docker compose build --pull openwa-api
docker compose up -d openwa-api
docker compose ps

🔒 6. Publicación Segura con Nginx, UFW y HTTPS

Crea el bloque de servidor en Nginx apuntando al puerto interno 2785 con soporte para WebSockets:

cat > /etc/nginx/sites-available/openwa <<'EOF'
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 80;
    server_name TU_DOMINIO.COM;

    client_max_body_size 25m;

    location / {
        proxy_pass http://127.0.0.1:2785;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $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;
    }
}
EOF

# Activar sitio y recargar Nginx
ln -sfn /etc/nginx/sites-available/openwa /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default
nginx -t && systemctl reload nginx

Asegura el firewall del sistema y emite el certificado SSL con Let's Encrypt:

# Configurar UFW
ufw default deny incoming
ufw default allow outgoing
ufw allow OpenSSH
ufw allow 'Nginx Full'
ufw --force enable

# Generar certificado HTTPS
certbot --nginx -d TU_DOMINIO.COM --non-interactive --agree-tos --email tu-correo@dominio.com --redirect

📲 7. Creación de Sesión y Vinculación de WhatsApp

curl -X POST "https://TU_DOMINIO.COM/api/sessions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: TU_API_KEY" \
  -d '{"name":"bot-ventas"}'