Guía de Instalación

Antes de empezar: Identifica tu tipo de proyecto

La instalación varía según la licencia que adquiriste. Identifica cuál es la tuya:

Requisitos del Servidor

VPS Recomendados

• Contabo — Desde $6.99/mes (4 vCPU, 8 GB RAM) — Mejor relación precio/rendimiento
• DigitalOcean — Desde $6/mes (1 vCPU, 1 GB RAM) — Fácil de usar
• Hetzner — Desde €3.79/mes (2 vCPU, 2 GB RAM) — Excelente en Europa
• Vultr — Desde $6/mes (1 vCPU, 1 GB RAM) — Múltiples ubicaciones

Paso 1: Instalar Dependencias del Sistema

# Actualizar sistema
sudo apt update && sudo apt upgrade -y

# Instalar PHP 8.2 y extensiones necesarias
sudo apt install php8.2 php8.2-fpm php8.2-mysql php8.2-mbstring \
  php8.2-xml php8.2-curl php8.2-zip php8.2-gd php8.2-bcmath \
  php8.2-intl php8.2-readline -y

# Instalar MySQL
sudo apt install mysql-server -y

# Instalar Node.js 18 (requerido para AMBOS tipos de licencia)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs -y

# Verificar versiones
node -v   # Debe mostrar v18.x.x
npm -v    # Debe mostrar 9.x.x o superior

# Instalar Composer (gestor de dependencias PHP)
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Instalar Supervisor (para workers en background)
sudo apt install supervisor -y

Servidor Web: elige uno

# Instalar Nginx
sudo apt install nginx -y

# Instalar Apache y módulos necesarios
sudo apt install apache2 libapache2-mod-php8.2 -y

# Habilitar módulos requeridos
sudo a2enmod rewrite headers ssl proxy_fcgi setenvif expires
sudo a2enconf php8.2-fpm
sudo systemctl restart apache2

Paso 2: Configurar Base de Datos

# Entrar a MySQL
sudo mysql -u root

# Crear base de datos y usuario
CREATE DATABASE app_wsp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'app_user'@'localhost' IDENTIFIED BY 'tu_password_seguro';
GRANT ALL PRIVILEGES ON *.* TO 'app_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Paso 3: Subir y Configurar Archivos

# Crear directorio del proyecto
sudo mkdir -p /var/www/automatizanegocios
cd /var/www/automatizanegocios

# Subir archivos (desde tu PC con scp)
scp -r ./proyecto/* usuario@tu-ip:/var/www/automatizanegocios/

# O con Git (solo licencia Código Fuente)
git clone https://tu-repo-privado.git /var/www/automatizanegocios

# Copiar y configurar archivo de entorno
cp .env.example .env
nano .env

Variables .env esenciales:

APP_NAME="AutomatizaNegocios"
APP_ENV=production
APP_KEY=base64:...
APP_DEBUG=false
APP_URL=https://tu-dominio.com

# Idioma predeterminado (es=Español, en=English, fr=Français, pt=Português)
APP_LOCALE=es
APP_FALLBACK_LOCALE=es

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=app_wsp
DB_USERNAME=app_user
DB_PASSWORD=tu_password_seguro

QUEUE_CONNECTION=database

Paso 4: Ejecutar Instalación

Este paso varía según tu tipo de licencia. Selecciona:

# Instalar dependencias PHP
composer install --no-dev --optimize-autoloader

# Generar application key
php artisan key:generate

# Ejecutar migraciones y seeders
php artisan migrate --seed

# Instalar OAuth2 (autenticación API)
php artisan passport:install

# Optimizar para producción
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Asignar permisos correctos
sudo chown -R www-data:www-data /var/www/automatizanegocios
sudo chmod -R 775 storage bootstrap/cache

# Instalar dependencias PHP
composer install --no-dev --optimize-autoloader

# ━━━ Instalar y compilar Frontend (OBLIGATORIO) ━━━
npm install
npm run build

# Verificar que se generó el manifest
ls -la public/build/manifest.json
# Debe mostrar el archivo. Si no existe, el build falló.

# Generar application key
php artisan key:generate

# Ejecutar migraciones y seeders
php artisan migrate --seed

# Instalar OAuth2 (autenticación API)
php artisan passport:install

# Optimizar para producción
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Asignar permisos correctos
sudo chown -R www-data:www-data /var/www/automatizanegocios
sudo chmod -R 775 storage bootstrap/cache

Paso 5: Configurar Servidor Web

sudo nano /etc/nginx/sites-available/automatizanegocios

server {
    listen 80;
    # Incluir wildcard para subdominios de tenants
    server_name tu-dominio.com www.tu-dominio.com *.tu-dominio.com;
    root /var/www/automatizanegocios/public;
    index index.php;

    # Tamaño máximo de uploads (archivos multimedia)
    client_max_body_size 64M;

    # Compresión gzip
    gzip on;
    gzip_types text/plain text/css application/json application/javascript;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # Bloquear acceso a archivos ocultos (.env, .git)
    location ~ /\.(?!well-known) { deny all; }

    # Cache de assets estáticos
    location ~* \.(css|js|jpg|jpeg|png|gif|ico|svg|woff2?)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

# Activar sitio y eliminar default
sudo ln -s /etc/nginx/sites-available/automatizanegocios /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default

# Verificar configuración
sudo nginx -t

# Reiniciar Nginx
sudo systemctl restart nginx

# Instalar SSL con Certbot (dominio principal)
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d tu-dominio.com -d www.tu-dominio.com

# ⚠️ Para SSL wildcard (subdominios de tenants), ver la
# Guía de Configuración → Subdominios para Tenants → Paso C

sudo nano /etc/apache2/sites-available/automatizanegocios.conf

<VirtualHost *:80>
    ServerName tu-dominio.com
    # ⚠️ Incluir wildcard para subdominios de tenants
    ServerAlias www.tu-dominio.com *.tu-dominio.com
    DocumentRoot /var/www/automatizanegocios/public

    <Directory /var/www/automatizanegocios/public>
        AllowOverride All
        Require all granted
        Options -Indexes +FollowSymLinks

        # Rewrite para Laravel
        <IfModule mod_rewrite.c>
            RewriteEngine On
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteRule ^ index.php [L]
        </IfModule>
    </Directory>

    # Logs
    ErrorLog ${APACHE_LOG_DIR}/automatizanegocios-error.log
    CustomLog ${APACHE_LOG_DIR}/automatizanegocios-access.log combined

    # Tamaño máximo de uploads
    <IfModule mod_php.c>
        php_value upload_max_filesize 64M
        php_value post_max_size 64M
    </IfModule>

    # Bloquear archivos ocultos (.env, .git)
    <FilesMatch "^\.(env|git|htaccess)">
        Require all denied
    </FilesMatch>

    # Cache de assets estáticos
    <IfModule mod_expires.c>
        ExpiresActive On
        ExpiresByType text/css "access plus 30 days"
        ExpiresByType application/javascript "access plus 30 days"
        ExpiresByType image/jpeg "access plus 30 days"
        ExpiresByType image/png "access plus 30 days"
        ExpiresByType image/svg+xml "access plus 30 days"
        ExpiresByType font/woff2 "access plus 30 days"
    </IfModule>
</VirtualHost>

# Activar sitio y desactivar default
sudo a2ensite automatizanegocios.conf
sudo a2dissite 000-default.conf

# Verificar configuración
sudo apachectl configtest

# Reiniciar Apache
sudo systemctl restart apache2

# Instalar SSL con Certbot (dominio principal)
sudo apt install certbot python3-certbot-apache -y
sudo certbot --apache -d tu-dominio.com -d www.tu-dominio.com

# ⚠️ Para SSL wildcard (subdominios de tenants), ver la
# Guía de Configuración → Subdominios para Tenants → Paso C

<IfModule mod_rewrite.c>
    RewriteEngine On

    # Forzar HTTPS en todos los dominios y subdominios
    RewriteCond %{HTTPS} off
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]

    # Ruteo Laravel (front controller)
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

# Bloquear acceso a archivos sensibles
<FilesMatch "^\.(env|git|htaccess)">
    Require all denied
</FilesMatch>

Paso 5.5: Configurar Firewall (UFW)

Configura el firewall para permitir solo los puertos necesarios:

# Habilitar UFW (si no está activo)
sudo ufw enable

# Permitir SSH (¡IMPORTANTE! Si no lo haces, perderás acceso al servidor)
sudo ufw allow 22

# Permitir HTTP y HTTPS
sudo ufw allow 80
sudo ufw allow 443

# Permitir puerto del Node Engine (si lo usas directamente)
# El puerto depende de tu configuración en .env (NODE_PORT)
sudo ufw allow 3000

# Verificar reglas activas
sudo ufw status verbose

Paso 6: Configurar Supervisor (Workers)

Supervisor mantiene los procesos en background corriendo permanentemente.

# 1. Instalar Supervisor
sudo apt install supervisor -y

sudo nano /etc/supervisor/conf.d/automatizanegocios-worker.conf

[program:an-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/automatizanegocios/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/automatizanegocios/storage/logs/worker.log
stopwaitsecs=3600

# Aplicar configuración
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start an-worker:*

Paso 7: Iniciar Node.js Engine (WhatsApp)

Este paso también varía según tu tipo de licencia:

# El engine viene como binario ejecutable
chmod +x /var/www/automatizanegocios/node-engine

# Ejecutar
cd /var/www/automatizanegocios
./node-engine &

# Instalar dependencias del engine
cd /var/www/automatizanegocios/node-engine
npm install

# Ejecutar en producción
node src/index.js &

# O usar PM2 para gestión de procesos (recomendado)
sudo npm install -g pm2
pm2 start src/index.js --name "wsp-engine"
pm2 save
pm2 startup

Paso 8: Verificar Instalación

1. Visita https://tu-dominio.com — deberías ver la pantalla de login
2. Ingresa con las credenciales del seeder: admin@admin.com / password
3. Verifica que el Dashboard Central cargue correctamente
4. Crea un tenant de prueba y verifica que accede a su panel
5. Accede al subdominio del tenant: https://nombre-tenant.tu-dominio.com — debe mostrar la pantalla de login del tenant
6. Verifica el worker: sudo supervisorctl status
7. Verifica el Node Engine: revisa que el proceso esté corriendo
8. Verifica el firewall: sudo ufw status
9. Verifica el SSL wildcard: sudo certbot certificates — debe incluir *.tu-dominio.com

# Lista de verificación rápida desde terminal:
sudo supervisorctl status            # Worker corriendo
ps aux | grep node                   # Node Engine corriendo
sudo ufw status                      # Firewall activo
sudo certbot certificates            # SSL con wildcard
curl -I https://tu-dominio.com       # Dominio principal OK
dig test.tu-dominio.com +short       # DNS wildcard resuelve

Resumen Rápido por Licencia

Troubleshooting

🔴 Vite manifest not found (Error 500)

Causa: Los assets del frontend no fueron compilados. Esto solo ocurre con la licencia Código Fuente. La licencia Compilado ya incluye public/build/.

Solución:

cd /var/www/automatizanegocios

# Verificar que Node.js está instalado
node -v    # Debe mostrar v18+
npm -v     # Debe mostrar 9+

# Si NO está instalado, instálalo primero:
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs -y

# Instalar dependencias y compilar
npm install
npm run build

# Verificar que se creó el manifest
ls -la public/build/manifest.json

# Corregir permisos
sudo chown -R www-data:www-data public/build

Si hay errores de memoria al compilar:

NODE_OPTIONS="--max-old-space-size=1024" npm run build

🔴 npm: command not found

Causa: Node.js no está instalado en el servidor.

Solución:

# NO uses "apt install npm" — instala una versión vieja
# Usa el repositorio oficial de NodeSource:
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs -y

# Verificar
node -v && npm -v

🟡 Error 500 / Página en blanco

• Revisa el log: tail -50 storage/logs/laravel.log
• Verifica permisos: sudo chmod -R 775 storage bootstrap/cache
• Verifica que .env esté configurado correctamente
• Limpia cachés: php artisan config:clear && php artisan cache:clear && php artisan view:clear
• Regenera la key: php artisan key:generate

🟡 El interfaz aparece en inglés

• Verifica que APP_LOCALE=es en tu .env
• Ejecuta: php artisan config:clear
• Idiomas disponibles: es, en, fr, pt

🟡 No se conecta WhatsApp

• Verifica que el Node Engine esté corriendo: ps aux | grep node
• Revisa el puerto en .env (variable NODE_PORT)
• Verifica firewall: sudo ufw allow 3000 (o el puerto configurado)
• Revisa logs del engine

🟡 Error de permisos al escribir en storage

sudo chown -R www-data:www-data /var/www/automatizanegocios
sudo chmod -R 775 storage bootstrap/cache
sudo chmod -R 775 public/build  # Solo si existe

🟡 Certbot SSL falla

• Verifica que el dominio apunte a tu IP: dig tu-dominio.com
• Verifica que el puerto 80 esté abierto: sudo ufw allow 80 && sudo ufw allow 443
• Asegúrate de que el servidor web esté corriendo antes de ejecutar certbot

🟡 Subdominio muestra otro sitio o landing page

• Verifica que *.tu-dominio.com esté en server_name (Nginx) o ServerAlias (Apache)
• Verifica que el VirtualHost SSL (puerto 443) también incluya el wildcard
• Reinicia el servidor web después de cambios: sudo systemctl restart nginx o apache2

🟡 Subdominio muestra "No es seguro" en HTTPS

• Tu certificado SSL no cubre *.tu-dominio.com
• Necesitas un certificado wildcard: ver Guía de Configuración → Subdominios → Paso C
• Verifica con: sudo certbot certificates — debe mostrar *.tu-dominio.com
• Después de generar el wildcard, reinicia Apache/Nginx y limpia cache del navegador

🟡 DNS wildcard no resuelve

• Verifica que creaste un registro A con hostname * en tu panel DNS
• Verifica que los nameservers están donde crees: dig NS tu-dominio.com
• Si los nameservers son de DigitalOcean, configura el DNS ahí (no en GoDaddy)
• Espera 5-30 minutos para propagación DNS
• Verifica propagación: whatsmydns.net

🔴 Campañas no se envían (0 sent, estado "Registrado")

• Causa más probable: Supervisor no está instalado o el worker no está corriendo
• Verifica: sudo supervisorctl status
• Si dice command not found: sudo apt install supervisor -y y configúralo (ver Paso 6)
• Si muestra STOPPED o FATAL: sudo supervisorctl restart an-worker:*
• Prueba procesar un job manual: php artisan queue:work --once

🔴 Error cURL 28: SSL connection timeout a Evolution API

• Causa: El servidor SaaS no puede conectar con la Evolution API
• Verifica que Evolution API esté corriendo: curl -I --connect-timeout 10 EVOLUTION_API_URL
• Si dice "Service is not reachable": el servicio de Evolution API está caído, reinícialo
• Si da timeout: verifica que el servidor de Evolution API tiene suficientes recursos (RAM/CPU)
• Diagnóstico rápido:

  # Verificar DNS
  dig tu-evolution-api.dominio.com +short
  
  # Verificar conectividad TCP
  timeout 5 bash -c 'cat < /dev/tcp/HOST/443' && echo "OK" || echo "FALLA"
  
  # Verificar con curl
  curl -Ik --connect-timeout 10 https://tu-evolution-api.dominio.com

🔴 Evolution API se cae frecuentemente

• Causa más probable: Servidor con recursos insuficientes (RAM/CPU)
• Si usas EasyPanel con Docker, verifica:
  • CPU no debe estar al 100% constantemente
  • RAM no debe superar el 85%
  • Cada servicio Docker consume RAM (Chatwoot ~1.5GB, Evolution API ~512MB, Redis ~128MB, PostgreSQL ~256MB)
• Requisitos mínimos del servidor de Evolution API:

  Servicios	RAM Mínima	Recomendada
  Solo Evolution API	1 GB	2 GB
  Evolution API + Chatwoot	4 GB	8 GB
  Evolution API + Chatwoot + n8n	4 GB	8 GB

• Solución rápida temporal: Agregar swap al servidor:

  sudo fallocate -l 2G /swapfile
  sudo chmod 600 /swapfile
  sudo mkswap /swapfile
  sudo swapon /swapfile
  echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

• Solución definitiva: Aumentar RAM del servidor (resize del droplet en DigitalOcean)

🟡 Worker Supervisor muestra FATAL

• Revisa el log: tail -50 /var/www/automatizanegocios/storage/logs/worker.log
• Causas comunes: error de PHP, falta de permisos, base de datos no accesible
• Reiniciar: sudo supervisorctl restart an-worker:*
• Si persiste, corre manualmente para ver el error: php artisan queue:work --once

Referencia Rápida de Mantenimiento

Comandos útiles para el día a día del servidor:

# ===== WORKERS Y COLAS =====
sudo supervisorctl status                      # Ver estado del worker
sudo supervisorctl restart an-worker:*         # Reiniciar worker
php artisan queue:work --once                  # Procesar 1 job manualmente
php artisan queue:retry all                    # Reintentar jobs fallidos
php artisan queue:flush                        # Limpiar jobs fallidos

# ===== CACHÉ Y CONFIGURACIÓN =====
php artisan config:clear                       # Limpiar cache de config
php artisan cache:clear                        # Limpiar cache general
php artisan view:clear                         # Limpiar cache de vistas
php artisan route:clear                        # Limpiar cache de rutas
php artisan optimize                           # Optimizar para producción

# ===== LOGS =====
tail -100 storage/logs/laravel.log             # Ver últimos logs
tail -f storage/logs/laravel.log               # Seguir logs en vivo
tail -50 storage/logs/worker.log               # Ver logs del worker

# ===== SERVIDOR =====
sudo systemctl restart apache2                 # Reiniciar Apache
sudo systemctl restart nginx                   # Reiniciar Nginx
sudo systemctl restart php8.2-fpm              # Reiniciar PHP-FPM
sudo certbot renew --dry-run                   # Probar renovación SSL

# ===== BASE DE DATOS =====
php artisan migrate:status                     # Ver estado de migraciones
php artisan db:seed --class=NombreSeeder       # Ejecutar seeder específico

# ===== MONITOREO =====
free -h                                        # Ver uso de RAM
df -h                                          # Ver uso de disco
top -bn1 | head -5                             # Ver uso de CPU
sudo ufw status                                # Ver reglas de firewall