---
id: "DEVOPS-001"
title: "Guia CI/CD"
type: "Guide"
status: "Published"
priority: "P1"
version: "1.0.0"
created_date: "2026-01-07"
updated_date: "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)

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

#### 2. SSH (VPS/Bare Metal)

```yaml
# 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)

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

#### 4. AWS S3 + CloudFront (Frontend)

```yaml
# 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)

```bash
# 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

```bash
# 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

```bash
# 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

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

### Frontend

```bash
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)