Runbook: Deploy de Aplicaciones

Overview

Propósito: Deploy de Orchestrator (backend) y Sevastopol (frontend) desde desarrollo a producción.

Frecuencia: Semanal/quincenal (según roadmap)

Tiempo estimado: 30-45 minutos

Criticidad: 🔴 ALTA - Requiere downtime planificado

Prerequisites

Antes de iniciar deploy, verificar:

SSH access a servidor de producción
Git credentials configurados
Variables de entorno production en .env.production
Backup de base de datos completado (ver Runbook: Backup)
Tests passing en CI/CD (GitHub Actions green)
Downtime window aprobado por stakeholders

Procedure

Conectar a servidor de producción
Terminal window
```
ssh [email protected]
cd /opt/nostromo
```

Pull latest code

# Orchestrator
cd /opt/nostromo/orchestrator && git pull origin main

# Sevastopol
cd /opt/nostromo/sevastopol && git pull origin main

Install dependencies

cd /opt/nostromo/orchestrator && npm ci
cd /opt/nostromo/sevastopol && npm ci

Run database migrations

cd /opt/nostromo/orchestrator && npm run migrate:production

Build production bundles

cd /opt/nostromo/orchestrator && npm run build
cd /opt/nostromo/sevastopol && npm run build

Stop services
Terminal window
```
pm2 stop orchestrator sevastopol
```

Restart services

pm2 start orchestrator sevastopol && sleep 30

Verify service status
Terminal window
```
pm2 status
```

Verification

Health Checks

Ejecutar health checks para confirmar deploy exitoso:

# Orchestrator health endpoint
curl http://localhost:8000/health
# Expected: {"status":"ok","version":"1.2.3"}

# Sevastopol (via Nginx proxy)
curl http://localhost:80/
# Expected: HTTP 200 OK

Test Sample API Call

# Login (obtener JWT)
curl -X POST http://localhost:8000/api/command/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"***"}'

# Expected: {"token":"eyJhbGc..."}

Monitor Logs

# PM2 logs
pm2 logs orchestrator --lines 50
pm2 logs sevastopol --lines 50

# systemd logs
sudo journalctl -u orchestrator -n 50 --no-pager
sudo journalctl -u sevastopol -n 50 --no-pager

Buscar errores:

❌ ERROR, FATAL, UnhandledPromiseRejection
✅ Server listening on port 8000, Build complete

Smoke Tests

Ejecutar smoke tests mínimos:

Login en Sevastopol funciona
Dashboard carga datos
API /api/common/indicadores retorna UF/UTM
Query a tenant específico funciona (verificar multi-tenancy)

Rollback

Si deploy falla o produce errores críticos:

Revert Git commits

cd /opt/nostromo/orchestrator && git log --oneline -5
git checkout <previous-commit-hash>

Restore database backup

Ver Runbook: Backup - sección “Restore Procedure”.

cd /opt/nostromo/backups && ls -lht | head -10
psql -U postgres -d nostromo < backup_2026-01-18_pre-deploy.sql

Rebuild with previous code
Terminal window
```
npm ci && npm run build
```
Restart services
Terminal window
```
pm2 restart orchestrator sevastopol
```
Verify rollback
Terminal window
```
curl http://localhost:8000/health
```

Post-Deploy

Update Changelog

Documentar deploy en changelog interno:

## 2026-01-18 - Production Deploy v1.2.3

**Changes**:

- Feature: Added admin endpoints for capital management
- Fix: Corrected PPM calculation for regime B
- Chore: Updated dependencies

**Migration**: 002_add_admin_indexes.sql
**Downtime**: 3 minutes
**Rolled back**: No

Notify Team

Comunicar deploy exitoso:

Slack: #deployments channel
Email: stakeholders (si cambios mayores)

Monitor for 24h

Monitorear métricas post-deploy por 24 horas:

Error rate (debe mantenerse baseline o bajar)
Response time (no debe aumentar significativamente)
User complaints (support tickets)

Troubleshooting

Service won’t start

Síntoma: pm2 status muestra errored o stopped.

Debugging:

pm2 logs orchestrator --err --lines 100
# Buscar stack trace

Causas comunes:

Puerto ya en uso: Error: listen EADDRINUSE :::8000
- Fix: Matar proceso anterior kill -9 $(lsof -t -i:8000)
Missing env vars: Error: JWT_SECRET is not defined
- Fix: Verificar .env.production existe y está poblado
Database connection failed: Error: connect ECONNREFUSED
- Fix: Verificar PostgreSQL running sudo systemctl status postgresql

Migrations fail

Síntoma: npm run migrate:production exits with error.