template-saas/docs/02-devops/CICD-GUIDE.md

id	title	type	status	priority	version	created_date	updated_date
DEVOPS-001	Guia CI/CD	Guide	Published	P1	1.0.0	2026-01-07	2026-01-10

CI/CD Guide - Template SaaS

Fecha: 2026-01-07 Estado: Configurado

---

Resumen

Pipeline CI/CD configurado con GitHub Actions para automatización de tests, builds y deployments.

---

Estructura de Archivos

.github/
└── workflows/
    ├── ci.yml          # Continuous Integration
    └── deploy.yml      # Deployment Pipeline

apps/
├── backend/
│   ├── Dockerfile      # Backend container
│   └── .dockerignore
└── frontend/
    ├── Dockerfile      # Frontend container (nginx)
    ├── nginx.conf      # Nginx configuration
    └── .dockerignore

docker-compose.yml      # Production stack
docker-compose.dev.yml  # Development infrastructure

---

CI Pipeline (ci.yml)

Triggers

• Push a main, master, develop
• Pull Requests a branches principales

Jobs

Job	Descripción
backend	Lint, tests, build del backend
frontend	Lint, type-check, build del frontend
security	npm audit para vulnerabilidades
ci-summary	Resumen del estado CI

Servicios

• PostgreSQL 15: Base de datos para tests
• Redis 7: Cache para tests de webhooks

Artifacts

• backend-dist: Build compilado del backend
• frontend-dist: Build optimizado del frontend

---

Deploy Pipeline (deploy.yml)

Triggers

• Push a main/master (staging automático)
• Workflow dispatch manual (staging/production)

Environments

Environment	Descripción
staging	Pre-producción
production	Producción

Métodos de Deployment

1. Docker (Recomendado)

# Variables de entorno requeridas
DOCKER_REGISTRY: ghcr.io/your-org
DOCKER_USERNAME: your-username
DOCKER_PASSWORD: ${{ secrets.GITHUB_TOKEN }}

2. SSH (VPS/Bare Metal)

# Secrets requeridos
SSH_HOST: your-server.com
SSH_USER: deploy
SSH_PRIVATE_KEY: -----BEGIN RSA PRIVATE KEY-----...
DEPLOY_PATH: /var/www/template-saas

3. Vercel (Frontend)

# Secrets requeridos
VERCEL_TOKEN: xxx
VERCEL_ORG_ID: xxx
VERCEL_PROJECT_ID: xxx

4. AWS S3 + CloudFront (Frontend)

# Secrets requeridos
AWS_ACCESS_KEY_ID: xxx
AWS_SECRET_ACCESS_KEY: xxx
AWS_S3_BUCKET: template-saas-frontend
CLOUDFRONT_DISTRIBUTION_ID: E1234567890

---

Desarrollo Local con Docker

Iniciar infraestructura (recomendado)

# Solo Postgres + Redis
docker-compose -f docker-compose.dev.yml up -d

# Con UI de administración
docker-compose -f docker-compose.dev.yml up -d --profile tools

URLs de desarrollo

Servicio	URL
PostgreSQL	localhost:5432
Redis	localhost:6379
Adminer (DB UI)	http://localhost:8080
Redis Commander	http://localhost:8081

Ejecutar aplicaciones en desarrollo

# Backend (terminal 1)
cd apps/backend
npm run start:dev

# Frontend (terminal 2)
cd apps/frontend
npm run dev

---

Stack Completo (Docker)

Build y ejecución

# Build de todos los servicios
docker-compose build

# Iniciar todo el stack
docker-compose up -d

# Ver logs
docker-compose logs -f

# Detener
docker-compose down

URLs de producción local

Servicio	URL
Frontend	http://localhost:3000
Backend API	http://localhost:3001
Health Check	http://localhost:3001/health

---

Configuración de Secrets en GitHub

Repository Settings > Secrets and Variables > Actions

Secrets (sensibles)

# Database
DB_PASSWORD=xxx

# JWT
JWT_SECRET=xxx

# Stripe
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

# Email
SENDGRID_API_KEY=SG.xxx

# AI
OPENROUTER_API_KEY=sk-or-xxx

# Deployment
SSH_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----
DOCKER_PASSWORD=xxx
VERCEL_TOKEN=xxx
AWS_SECRET_ACCESS_KEY=xxx

Variables (no sensibles)

# Deployment method
DEPLOY_METHOD=docker  # docker | ssh | vercel | s3

# URLs
API_URL=https://api.example.com
APP_URL=https://app.example.com

# AWS
AWS_REGION=us-east-1

# Docker
DOCKER_REGISTRY=ghcr.io/your-org

---

Health Checks

Backend

curl http://localhost:3001/health
# Response: { "status": "ok", "info": {...} }

Frontend

curl http://localhost:3000/health
# Response: healthy

---

Troubleshooting

CI falla en tests

1. Verificar que PostgreSQL/Redis estén healthy
2. Revisar logs del job
3. Ejecutar tests localmente: npm test

Build falla

1. Verificar tipos: npx tsc --noEmit
2. Verificar dependencias: npm ci

Deploy falla

1. Verificar secrets/variables configurados
2. Revisar logs del workflow
3. Verificar conectividad al servidor/servicio

---

Mejoras Futuras

• Code coverage reports (Codecov)
• E2E tests con Playwright
• Performance testing
• Rollback automático
• Blue/Green deployments
• Notifications (Slack/Discord)