806612a4db
- Renombrar 02-integraciones/ → 03-integraciones/ (resolver prefijo duplicado) - Renombrar 02-devops/ → 04-devops/ (resolver prefijo duplicado) - Renombrar architecture/ → 97-adr/ (agregar prefijo numerico) - Actualizar _MAP.md con nueva estructura y version 2.1.0 Estructura final: - 00-vision-general/ - 01-modulos/ - 02-especificaciones/ - 03-integraciones/ - 04-devops/ - 97-adr/ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
291 lines
5.0 KiB
Markdown
291 lines
5.0 KiB
Markdown
---
|
|
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)
|