# 🛡️ Sistema de Despliegue Blindado - 4Alarm

## 🎯 Resumen Ejecutivo

Este sistema implementa una **arquitectura de despliegue automatizada y blindada** para 4Alarm que garantiza que **NUNCA** se sirva código fuente sin compilar, protegiendo archivos sensibles y asegurando que solo se exponga contenido compilado y optimizado.

---

## ✨ Características Principales

### 🔒 Seguridad Total
- ✅ **Solo sirve contenido compilado** desde `frontend/build/`
- ✅ **Bloquea archivos sensibles**: `.env`, `.git`, `package.json`, código fuente
- ✅ **Sin fallback inseguro**: Si no hay build, muestra página de error controlada
- ✅ **Headers de seguridad**: XSS Protection, Frame Options, Content-Type Options

### 🚀 Despliegue Automatizado
- ✅ **Endpoint `/api/deploy`**: Ejecuta git pull + npm install + npm run build
- ✅ **Validación automática**: Verifica que el build sea válido antes de servir
- ✅ **Logs detallados**: Seguimiento completo del proceso de despliegue
- ✅ **Manejo de errores**: Detiene el proceso si falla la compilación

### 🏗️ Arquitectura Robusta
- ✅ **Backend FastAPI** (puerto 8000): API y endpoint de despliegue
- ✅ **Servidor estático Node.js** (puerto 3000): Sirve solo `build/`
- ✅ **Separación de responsabilidades**: Backend y frontend independientes
- ✅ **PM2 ready**: Scripts para gestión con PM2

---

## 📦 Archivos Creados

```
4alarm/
├── backend/routes/deploy.py       # Endpoint de despliegue automatizado
├── static_server.js               # Servidor estático blindado
├── package.json                   # Dependencias del servidor estático
├── setup.sh                       # Script de instalación automatizada
├── DEPLOYMENT_GUIDE.md            # Guía completa de despliegue
└── README_DEPLOYMENT.md           # Este archivo
```

---

## 🚀 Inicio Rápido

### Instalación Automática

```bash
cd /root/proyectos_web/4alarm
./setup.sh
```

El script instalará:
1. Dependencias del servidor estático (Express)
2. Dependencias del frontend (React + librerías)
3. Compilará el frontend por primera vez
4. Instalará dependencias del backend (FastAPI)
5. Verificará la configuración

### Instalación Manual

```bash
# 1. Instalar servidor estático
npm install

# 2. Instalar y compilar frontend
cd frontend
npm install
npm run build
cd ..

# 3. Instalar backend
cd backend
pip3 install -r requirements.txt
cd ..
```

---

## 🎮 Uso del Sistema

### Iniciar Servidores

**Terminal 1 - Backend FastAPI:**
```bash
cd backend
uvicorn server:app --host 0.0.0.0 --port 8000 --reload
```

**Terminal 2 - Servidor Estático:**
```bash
npm start
# O con PM2: npm run pm2:start
```

### Acceder a la Aplicación

- **Frontend**: http://localhost:3000
- **API Backend**: http://localhost:8000
- **Documentación API**: http://localhost:8000/docs

---

## 🔄 Despliegue Automatizado

### Endpoint de Despliegue

**POST** `/api/deploy`

Ejecuta automáticamente:
1. `git pull origin main` - Actualiza código
2. `npm install` - Actualiza dependencias
3. `npm run build` - Compila frontend
4. Valida que el build sea correcto

### Ejemplo de Uso

```bash
# Desplegar nueva versión
curl -X POST http://localhost:8000/api/deploy

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

### Respuesta Exitosa

```json
{
  "success": true,
  "message": "Despliegue completado exitosamente",
  "build_path": "/root/proyectos_web/4alarm/frontend/build",
  "logs": "=== PASO 1: Actualizando repositorio...\n..."
}
```

---

## 🔒 Protecciones de Seguridad

### Archivos Bloqueados

El servidor **NUNCA** servirá:
- `.env` - Variables de entorno
- `.git/` - Repositorio Git
- `package.json` - Configuración
- `*.py` - Scripts Python
- `*.sh` - Scripts shell
- `node_modules/` - Dependencias
- `backend/` - Código backend
- `src/` - Código fuente frontend

### Validaciones Implementadas

1. **Verificación de build**: Comprueba que existe `build/index.html`
2. **Validación de contenido**: Verifica archivos estáticos en `build/static/`
3. **Página de error controlada**: Si no hay build, muestra página elegante
4. **Sin fallback inseguro**: NUNCA sirve desde `src/` o raíz del proyecto

---

## 📊 Monitoreo y Logs

### Ver Estado del Despliegue

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

### Logs del Servidor Estático (PM2)

```bash
npm run pm2:logs
```

### Reiniciar Servidor

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

---

## 🛠️ Troubleshooting

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

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

### Problema: "Error en compilación"

**Diagnóstico:**
```bash
cd frontend
npm install
npm run build
# Revisar logs de error
```

### Problema: "Cambios no se reflejan"

**Solución:**
```bash
# 1. Recompilar
cd frontend && npm run build

# 2. Reiniciar servidor
cd .. && npm run pm2:restart

# 3. Limpiar caché del navegador (Ctrl + Shift + R)
```

---

## 📚 Documentación Completa

Para información detallada, consulta:
- **[DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md)** - Guía completa de despliegue

---

## 🎯 Checklist de Verificación

Antes de poner en producción, verifica:

- [ ] Backend corriendo en puerto 8000
- [ ] Servidor estático corriendo en puerto 3000
- [ ] Carpeta `frontend/build/` existe y contiene `index.html`
- [ ] Endpoint `/api/deploy/status` retorna `ready_to_serve: true`
- [ ] Archivos sensibles bloqueados (prueba acceder a `/.env`)
- [ ] Headers de seguridad configurados
- [ ] PM2 configurado para auto-restart
- [ ] Variables de entorno configuradas en `backend/.env`

---

## 🔐 Reglas de Oro del Despliegue

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

---

## 📞 Soporte

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

**Versión:** 1.0.0  
**Fecha:** 2026-08-05  
**Autor:** Cline - Arquitecto DevOps

---

## 🎉 ¡Listo para Producción!

El sistema está completamente configurado y listo para desplegar de forma segura. Todos los componentes están blindados contra exposición de código fuente y archivos sensibles.

**¡Feliz despliegue! 🚀**