# 🚀 Guía de Despliegue Automatizado - 4Alarm

## 📋 Índice
1. [Arquitectura de Despliegue](#arquitectura-de-despliegue)
2. [Instalación Inicial](#instalación-inicial)
3. [Uso del Sistema de Despliegue](#uso-del-sistema-de-despliegue)
4. [Seguridad y Blindaje](#seguridad-y-blindaje)
5. [Troubleshooting](#troubleshooting)

---

## 🏗️ Arquitectura de Despliegue

El sistema 4Alarm implementa una arquitectura de despliegue blindada que garantiza:

- ✅ **Compilación obligatoria** antes de servir contenido
- ✅ **Servidor estático** apunta SOLO a `/frontend/build/`
- ✅ **Bloqueo total** de archivos sensibles (.env, .git, código fuente)
- ✅ **Validación automática** del build generado
- ✅ **Manejo de errores** sin fallback a carpetas inseguras

### Componentes

```
4alarm/
├── backend/
│   ├── server.py              # FastAPI backend (puerto 8000)
│   └── routes/
│       └── deploy.py          # Endpoint de despliegue automatizado
├── frontend/
│   ├── src/                   # Código fuente (NO SERVIDO)
│   ├── build/                 # Carpeta compilada (SERVIDA)
│   └── package.json           # Scripts de build
├── static_server.js           # Servidor Node.js blindado (puerto 3000)
└── package.json               # Dependencias del servidor estático
```

---

## 🔧 Instalación Inicial

### 1. Instalar dependencias del servidor estático

```bash
cd /root/proyectos_web/4alarm
npm install
```

### 2. Compilar el frontend por primera vez

```bash
cd frontend
npm install
npm run build
```

### 3. Iniciar el servidor estático

**Opción A: Modo desarrollo (con auto-reload)**
```bash
npm run dev
```

**Opción B: Modo producción**
```bash
npm start
```

**Opción C: Con PM2 (recomendado para producción)**
```bash
npm run pm2:start
```

### 4. Iniciar el backend FastAPI

```bash
cd backend
pip install -r requirements.txt
uvicorn server:app --host 0.0.0.0 --port 8000 --reload
```

---

## 🚀 Uso del Sistema de Despliegue

### Endpoint de Despliegue Automatizado

El sistema incluye un endpoint que ejecuta el ciclo completo de despliegue:

**POST** `/api/deploy`

#### Flujo de ejecución:

1. **Git Pull** - Actualiza el código desde el repositorio
2. **npm install** - Instala/actualiza dependencias
3. **npm run build** - Compila el frontend
4. **Validación** - Verifica que el build sea válido

#### Ejemplo de uso con curl:

```bash
curl -X POST http://localhost:8000/api/deploy \
  -H "Content-Type: application/json" \
  -d '{"force_rebuild": false}'
```

#### Ejemplo de uso con Python:

```python
import requests

response = requests.post('http://localhost:8000/api/deploy')
result = response.json()

if result['success']:
    print(f"✅ Despliegue exitoso: {result['message']}")
    print(f"📁 Build en: {result['build_path']}")
else:
    print(f"❌ Error: {result['error']}")
```

### Verificar Estado del Despliegue

**GET** `/api/deploy/status`

```bash
curl http://localhost:8000/api/deploy/status
```

Respuesta:
```json
{
  "build_exists": true,
  "build_valid": true,
  "build_path": "/root/proyectos_web/4alarm/frontend/build",
  "ready_to_serve": true,
  "index_html_size": 3456,
  "index_html_modified": 1704567890.123
}
```

---

## 🔒 Seguridad y Blindaje

### Archivos Bloqueados

El servidor estático **NUNCA** servirá estos archivos:

- ❌ `.env` - Variables de entorno
- ❌ `.git/` - Repositorio Git
- ❌ `package.json` - Configuración npm
- ❌ `*.py` - Scripts Python
- ❌ `*.sh` - Scripts shell
- ❌ `*.config.js` - Archivos de configuración
- ❌ `node_modules/` - Dependencias
- ❌ `backend/` - Código del backend
- ❌ `src/` - Código fuente del frontend

### Página de Error Controlada

Si la carpeta `build/` no existe, el servidor muestra una página de error elegante en lugar de exponer el código fuente:

```
🚧 Sistema en Actualización
El sistema 4Alarm está siendo actualizado en este momento.
⏳ Despliegue en Proceso
```

### Headers de Seguridad

El servidor estático incluye headers de seguridad:

```
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache (para index.html)
```

---

## 🛠️ Troubleshooting

### Problema: "Carpeta build/ no encontrada"

**Solución:**
```bash
cd frontend
npm run build
```

O usa el endpoint de despliegue:
```bash
curl -X POST http://localhost:8000/api/deploy
```

### Problema: "Error en npm run build"

**Diagnóstico:**
```bash
cd frontend
npm install
npm run build
```

Revisa los logs para identificar errores de compilación.

### Problema: "El servidor muestra página de error"

**Verificación:**
```bash
# Verificar que existe build/
ls -la frontend/build/

# Verificar que existe index.html
ls -la frontend/build/index.html

# Verificar estado del despliegue
curl http://localhost:8000/api/deploy/status
```

### Problema: "Cambios no se reflejan en el navegador"

**Solución:**
1. Limpiar caché del navegador (Ctrl + Shift + R)
2. Verificar que el build se ejecutó correctamente
3. Reiniciar el servidor estático:

```bash
npm run pm2:restart
```

### Problema: "Error al ejecutar git pull"

**Solución:**
```bash
cd /root/proyectos_web/4alarm
git status
git stash  # Si hay cambios locales
git pull origin main
```

---

## 📊 Monitoreo con PM2

### Ver logs en tiempo real:
```bash
npm run pm2:logs
```

### Ver estado del proceso:
```bash
pm2 status
```

### Reiniciar el servidor:
```bash
npm run pm2:restart
```

### Detener el servidor:
```bash
npm run pm2:stop
```

---

## 🔄 Flujo de Actualización Completo

### Actualización Manual:

```bash
# 1. Actualizar código
cd /root/proyectos_web/4alarm
git pull origin main

# 2. Actualizar dependencias del frontend
cd frontend
npm install

# 3. Compilar frontend
npm run build

# 4. Reiniciar servidor estático
cd ..
npm run pm2:restart
```

### Actualización Automatizada:

```bash
# Un solo comando ejecuta todo el flujo
curl -X POST http://localhost:8000/api/deploy
```

---

## 📝 Notas Importantes

1. **NUNCA** apuntes el servidor estático a la raíz del proyecto o a `src/`
2. **SIEMPRE** verifica que el build se completó exitosamente antes de servir
3. **NUNCA** hagas fallback silencioso a carpetas no compiladas
4. **SIEMPRE** valida que `build/index.html` existe antes de servir
5. **MANTÉN** los logs de despliegue para debugging

---

## 🎯 Checklist de Despliegue

- [ ] Backend FastAPI corriendo en puerto 8000
- [ ] Servidor estático corriendo en puerto 3000
- [ ] Carpeta `frontend/build/` existe y es válida
- [ ] Endpoint `/api/deploy/status` retorna `ready_to_serve: true`
- [ ] Archivos sensibles bloqueados correctamente
- [ ] Headers de seguridad configurados
- [ ] PM2 configurado para auto-restart
- [ ] Logs de despliegue accesibles

---

## 📞 Soporte

Para reportar problemas o solicitar mejoras, contacta al equipo de desarrollo de 4Alarm.

**Versión:** 1.0.0  
**Última actualización:** 2026-08-05