# Hermes Gateway — Guía de despliegue en Plesk (chroot, sin systemd)
## Dominio: `codi.iaprosystems.com` · Node.js v22 · Python 3.6.8

---

## Archivos del paquete de despliegue

```
hermes-plesk-deploy/
├── install.sh            ← Script principal de instalación
├── index.js              ← App Node.js (servidor Express + webhook Telegram)
├── package.json          ← Dependencias Node.js
├── ecosystem.config.js   ← Configuración PM2
├── .env.example          ← Plantilla de variables de entorno
├── register_webhook.sh   ← Helper para registrar/verificar webhook
└── INSTRUCCIONES.md      ← Este archivo
```

---

## PASO 1 — Preparar credenciales

Antes de cualquier cosa, reúne:

| Variable | Dónde obtenerla |
|---|---|
| `TELEGRAM_BOT_TOKEN` | Habla con [@BotFather](https://t.me/botfather) → `/newbot` |
| `TELEGRAM_WEBHOOK_SECRET` | Genera: `openssl rand -hex 32` |
| `OPENROUTER_API_KEY` | https://openrouter.ai/keys |
| `HERMES_PROFILE` | Nombre de la carpeta en `~/.hermes/profiles/` (defecto: `default`) |

---

## PASO 2 — Subir archivos al servidor

### Opción A — FTP/SFTP (Plesk File Manager)

1. Conéctate al servidor con las credenciales FTP del dominio.
2. Sube **todos los archivos** (excepto `node_modules/`) a:
   ```
   /var/www/vhosts/iaprosystems.com/codi.iaprosystems.com/httpdocs/
   ```
3. Asegúrate de subir también el `.env.example` y renómbralo a `.env`.

### Opción B — SSH / rsync

```bash
rsync -avz --exclude=node_modules \
  hermes-plesk-deploy/ \
  usuario@codi.iaprosystems.com:/var/www/vhosts/iaprosystems.com/codi.iaprosystems.com/httpdocs/
```

---

## PASO 3 — Configurar .env en el servidor

```bash
cd /var/www/vhosts/iaprosystems.com/codi.iaprosystems.com/httpdocs/

# Editar con nano (disponible en Plesk sin systemd)
nano .env
```

Rellena todos los campos marcados con `PON_AQUI_...`. En especial:

```bash
TELEGRAM_BOT_TOKEN=123456789:ABCdef...
TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)   # pega el resultado
OPENROUTER_API_KEY=sk-or-...
HERMES_BIN=$(python3 -m site --user-base)/bin/hermes  # pega el resultado
```

Protege el archivo:

```bash
chmod 600 .env
```

---

## PASO 4 — Ejecutar el script de instalación

```bash
cd /var/www/vhosts/iaprosystems.com/codi.iaprosystems.com/httpdocs/
chmod +x install.sh
./install.sh
```

El script realizará automáticamente:

- ✅ Instalar `hermes-agent` via `pip --user`
- ✅ Instalar dependencias Node.js (`npm install`)
- ✅ Instalar PM2 en `~/.local/`
- ✅ Crear `ecosystem.config.js`
- ✅ Arrancar la app con PM2
- ✅ Configurar `cron @reboot` para persistencia sin systemd
- ✅ Registrar el webhook de Telegram

---

## PASO 5 — Configurar la app Node.js en el panel Plesk

> Esta configuración es necesaria para que Plesk/Nginx/LiteSpeed haga proxy
> de las peticiones HTTPS → Node.js interno en el puerto 3000.

### 5.1 Acceder a la configuración

1. **Panel Plesk** → **Dominios** → `codi.iaprosystems.com`
2. Clic en **Node.js** (en la sección "Desarrollo web")

### 5.2 Configuración de la app

| Campo | Valor |
|---|---|
| **Node.js version** | `22.x` (la más alta disponible) |
| **Application mode** | `Production` |
| **Application root** | `/httpdocs` |
| **Application startup file** | `index.js` |
| **Application URL** | `https://codi.iaprosystems.com` |

> ⚠️ **Application root** en Plesk es relativo a la raíz del dominio.
> Si el panel pide ruta absoluta, usa:
> `/var/www/vhosts/iaprosystems.com/codi.iaprosystems.com/httpdocs`

### 5.3 Variables de entorno en Plesk (opcional)

Si prefieres no usar `.env`, puedes añadir las variables en:
**Node.js** → **Environment Variables** → `+ Add variable`

Añade al menos:
- `NODE_ENV` = `production`
- `PORT` = `3000`

### 5.4 Instalar dependencias desde Plesk

En la sección Node.js del panel, haz clic en:
**"NPM install"** (o ejecuta `npm install` por SSH).

### 5.5 Proxy Nginx/LiteSpeed → Node.js

Plesk configura automáticamente el proxy reverso cuando detecta la app Node.js.
Si no lo hace automáticamente, ve a:

**Dominios** → `codi.iaprosystems.com` → **Apache & nginx Settings**

Y añade en **Additional nginx directives**:

```nginx
location /webhook {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    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;
    proxy_read_timeout 120s;
    proxy_send_timeout 120s;
}

location /health {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
}

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
}
```

---

## PASO 6 — Registrar el webhook de Telegram

### Opción A — Con el script helper

```bash
cd /var/www/vhosts/iaprosystems.com/codi.iaprosystems.com/httpdocs/
chmod +x register_webhook.sh

# Exportar variables
export TELEGRAM_BOT_TOKEN="TU_TOKEN"
export TELEGRAM_WEBHOOK_SECRET="TU_SECRET"
export WEBHOOK_URL="https://codi.iaprosystems.com/webhook"

# Registrar
./register_webhook.sh set

# Verificar estado
./register_webhook.sh info
```

### Opción B — Comando curl directo

```bash
curl -X POST "https://api.telegram.org/bot<TU_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://codi.iaprosystems.com/webhook",
    "secret_token": "<TU_WEBHOOK_SECRET>",
    "allowed_updates": ["message","callback_query","inline_query","edited_message"],
    "drop_pending_updates": true,
    "max_connections": 40
  }'
```

Respuesta esperada:
```json
{"ok": true, "result": true, "description": "Webhook was set"}
```

### Verificar webhook activo

```bash
curl "https://api.telegram.org/bot<TU_TOKEN>/getWebhookInfo"
```

---

## PASO 7 — Verificación completa

```bash
# 1. Ver estado de PM2
pm2 list

# 2. Ver logs en tiempo real
pm2 logs hermes-gateway

# 3. Test de salud local
curl http://localhost:3000/health

# 4. Test de salud desde exterior
curl https://codi.iaprosystems.com/health

# 5. Enviar mensaje de prueba al bot en Telegram
# → Abre Telegram, busca tu bot y envía "/start" o cualquier texto
```

---

## Arranque automático sin systemd (cron)

El script `install.sh` configura automáticamente:

```bash
@reboot sleep 30 && pm2 resurrect >> /var/www/.../logs/pm2-reboot.log 2>&1
```

Para verificarlo:
```bash
crontab -l
```

Para PM2 guardar el estado actual:
```bash
pm2 save
```

---

## Comandos de gestión diaria

```bash
# Ver estado
pm2 list
pm2 show hermes-gateway

# Logs
pm2 logs hermes-gateway            # en tiempo real
pm2 logs hermes-gateway --lines 100  # últimas 100 líneas

# Reiniciar / detener
pm2 restart hermes-gateway
pm2 stop hermes-gateway
pm2 start ecosystem.config.js

# Recargar sin downtime
pm2 reload hermes-gateway

# Limpiar logs
pm2 flush hermes-gateway

# Estado del webhook
./register_webhook.sh info

# Eliminar webhook (para depuración con polling local)
./register_webhook.sh delete
```

---

## Solución de problemas

### La app no arranca

```bash
pm2 logs hermes-gateway --err   # ver errores
node index.js                   # probar arranque manual
```

### Hermes no responde

```bash
# Verificar que el binario existe
ls -la $(python3 -m site --user-base)/bin/hermes

# Probar hermes directamente
hermes --profile default "hola"

# Revisar HERMES_BIN en .env
cat .env | grep HERMES_BIN
```

### El webhook no llega a la app

```bash
# Verificar que nginx/LiteSpeed hace proxy al puerto 3000
curl -v https://codi.iaprosystems.com/health

# Ver logs de nginx
tail -f /var/log/nginx/codi.iaprosystems.com.error.log

# Verificar que la app escucha
ss -tlnp | grep 3000
```

### Error 403 en /webhook

El `secret_token` enviado por Telegram no coincide con `TELEGRAM_WEBHOOK_SECRET` en `.env`.
Verifica que ambos valores sean idénticos (sin espacios extra).

### Python 3.6.8 — pip muy antiguo

```bash
# Actualizar pip para Python 3.6
python3 -m ensurepip --upgrade
python3 -m pip install --upgrade pip

# Si pip no está disponible, descargar get-pip.py
curl https://bootstrap.pypa.io/pip/3.6/get-pip.py -o get-pip.py
python3 get-pip.py --user
```

> ⚠️ Python 3.6 es EOL. `hermes-agent` puede requerir Python ≥ 3.8.
> En ese caso, solicita al soporte de Plesk que instalen Python 3.8+
> o usa un virtualenv con pyenv.

---

## Arquitectura del sistema

```
Telegram API
    │
    │ HTTPS POST /webhook
    ▼
Nginx/LiteSpeed (Plesk)
    │ proxy_pass http://127.0.0.1:3000
    ▼
Node.js Express (index.js) — PM2
    │ spawn()
    ▼
hermes CLI (Python, pip --user)
    │ OpenRouter API
    ▼
LLM Response → sendMessage → Telegram User
```

---

*Generado para codi.iaprosystems.com — Hermes Gateway v1.0.0*