rckrdmrd
928eb795e6
- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8 - Cambios en backend y frontend Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
455 lines
9.3 KiB
Markdown
455 lines
9.3 KiB
Markdown
# Guía de Despliegue - MiChangarrito
|
|
|
|
**Versión**: 1.0.0
|
|
**Última actualización**: 2026-01-07
|
|
**Autor**: @PERFIL_DEVOPS
|
|
|
|
---
|
|
|
|
## Tabla de Contenidos
|
|
|
|
1. [Requisitos](#requisitos)
|
|
2. [Despliegue Local (Docker)](#despliegue-local-docker)
|
|
3. [Despliegue en Producción](#despliegue-en-producción)
|
|
4. [CI/CD con GitHub Actions](#cicd-con-github-actions)
|
|
5. [Configuración de SSL](#configuración-de-ssl)
|
|
6. [Backups](#backups)
|
|
7. [Monitoreo](#monitoreo)
|
|
8. [Troubleshooting](#troubleshooting)
|
|
|
|
---
|
|
|
|
## Requisitos
|
|
|
|
### Requisitos de Sistema
|
|
|
|
| Componente | Mínimo | Recomendado |
|
|
|------------|--------|-------------|
|
|
| CPU | 2 cores | 4 cores |
|
|
| RAM | 4 GB | 8 GB |
|
|
| Disco | 20 GB | 50 GB SSD |
|
|
| SO | Ubuntu 22.04 LTS | Ubuntu 22.04 LTS |
|
|
|
|
### Software Requerido
|
|
|
|
```bash
|
|
# Docker y Docker Compose
|
|
docker --version # >= 24.0
|
|
docker-compose --version # >= 2.20
|
|
|
|
# Node.js (solo para desarrollo)
|
|
node --version # >= 20.0
|
|
npm --version # >= 10.0
|
|
```
|
|
|
|
### Instalación de Docker (Ubuntu)
|
|
|
|
```bash
|
|
# Actualizar paquetes
|
|
sudo apt update && sudo apt upgrade -y
|
|
|
|
# Instalar Docker
|
|
curl -fsSL https://get.docker.com -o get-docker.sh
|
|
sudo sh get-docker.sh
|
|
|
|
# Agregar usuario al grupo docker
|
|
sudo usermod -aG docker $USER
|
|
|
|
# Instalar Docker Compose
|
|
sudo apt install docker-compose-plugin -y
|
|
|
|
# Verificar instalación
|
|
docker --version
|
|
docker compose version
|
|
```
|
|
|
|
---
|
|
|
|
## Despliegue Local (Docker)
|
|
|
|
### 1. Clonar Repositorio
|
|
|
|
```bash
|
|
git clone https://github.com/isem/michangarrito.git
|
|
cd michangarrito
|
|
```
|
|
|
|
### 2. Configurar Variables de Entorno
|
|
|
|
```bash
|
|
# Copiar template
|
|
cp .env.docker .env
|
|
|
|
# Editar con tus credenciales
|
|
nano .env
|
|
```
|
|
|
|
**Variables importantes a configurar:**
|
|
|
|
```env
|
|
# Seguridad
|
|
JWT_SECRET=<generar-string-aleatorio-64-chars>
|
|
|
|
# Stripe (opcional para desarrollo)
|
|
STRIPE_SECRET_KEY=sk_test_xxx
|
|
STRIPE_WEBHOOK_SECRET=whsec_xxx
|
|
|
|
# WhatsApp (opcional para desarrollo)
|
|
WHATSAPP_TOKEN=xxx
|
|
WHATSAPP_VERIFY_TOKEN=xxx
|
|
```
|
|
|
|
### 3. Iniciar Servicios
|
|
|
|
```bash
|
|
# Usando el script de deploy
|
|
./deploy/scripts/deploy.sh
|
|
|
|
# O directamente con docker-compose
|
|
docker-compose up -d
|
|
```
|
|
|
|
### 4. Verificar Estado
|
|
|
|
```bash
|
|
# Ver estado de contenedores
|
|
docker-compose ps
|
|
|
|
# Ver logs
|
|
docker-compose logs -f
|
|
|
|
# Health checks
|
|
curl http://localhost:3141/api/v1/health
|
|
curl http://localhost:3140
|
|
```
|
|
|
|
### URLs de Desarrollo
|
|
|
|
| Servicio | URL |
|
|
|----------|-----|
|
|
| Frontend | http://localhost:3140 |
|
|
| Backend API | http://localhost:3141/api/v1 |
|
|
| API Docs (Swagger) | http://localhost:3141/api/v1/docs |
|
|
| WhatsApp Webhook | http://localhost:3143 |
|
|
|
|
---
|
|
|
|
## Despliegue en Producción
|
|
|
|
### 1. Preparar Servidor
|
|
|
|
```bash
|
|
# Conectar al servidor
|
|
ssh user@servidor.com
|
|
|
|
# Crear directorio
|
|
sudo mkdir -p /opt/michangarrito
|
|
sudo chown $USER:$USER /opt/michangarrito
|
|
cd /opt/michangarrito
|
|
|
|
# Clonar repositorio
|
|
git clone https://github.com/isem/michangarrito.git .
|
|
```
|
|
|
|
### 2. Configurar Environment de Producción
|
|
|
|
```bash
|
|
cp .env.docker .env
|
|
nano .env
|
|
```
|
|
|
|
**Configuración de producción:**
|
|
|
|
```env
|
|
# Database con password fuerte
|
|
DB_PASSWORD=<password-seguro-produccion>
|
|
|
|
# JWT con secret largo
|
|
JWT_SECRET=<string-aleatorio-64-chars-produccion>
|
|
|
|
# CORS para tu dominio
|
|
CORS_ORIGIN=https://michangarrito.com
|
|
|
|
# API URL de producción
|
|
VITE_API_URL=https://api.michangarrito.com/api/v1
|
|
|
|
# Activar perfil de producción (incluye nginx)
|
|
COMPOSE_PROFILES=production
|
|
|
|
# Stripe en modo live
|
|
STRIPE_SECRET_KEY=sk_live_xxx
|
|
STRIPE_WEBHOOK_SECRET=whsec_xxx
|
|
|
|
# WhatsApp
|
|
WHATSAPP_TOKEN=xxx
|
|
WHATSAPP_PHONE_NUMBER_ID=xxx
|
|
WHATSAPP_BUSINESS_ACCOUNT_ID=xxx
|
|
```
|
|
|
|
### 3. Configurar SSL con Let's Encrypt
|
|
|
|
```bash
|
|
# Instalar certbot
|
|
sudo apt install certbot -y
|
|
|
|
# Crear directorio para certificados
|
|
mkdir -p deploy/ssl
|
|
|
|
# Obtener certificado
|
|
sudo certbot certonly --standalone -d michangarrito.com -d api.michangarrito.com
|
|
|
|
# Copiar certificados
|
|
sudo cp /etc/letsencrypt/live/michangarrito.com/fullchain.pem deploy/ssl/
|
|
sudo cp /etc/letsencrypt/live/michangarrito.com/privkey.pem deploy/ssl/
|
|
sudo chown $USER:$USER deploy/ssl/*.pem
|
|
```
|
|
|
|
### 4. Habilitar HTTPS en Nginx
|
|
|
|
Editar `deploy/nginx/conf.d/default.conf` y descomentar la sección de HTTPS.
|
|
|
|
### 5. Iniciar en Producción
|
|
|
|
```bash
|
|
./deploy/scripts/deploy.sh --production --build
|
|
```
|
|
|
|
### 6. Configurar Renovación Automática de SSL
|
|
|
|
```bash
|
|
# Agregar cron job
|
|
sudo crontab -e
|
|
|
|
# Agregar línea:
|
|
0 3 * * * certbot renew --quiet && docker-compose -f /opt/michangarrito/docker-compose.yml restart nginx
|
|
```
|
|
|
|
---
|
|
|
|
## CI/CD con GitHub Actions
|
|
|
|
### Configuración
|
|
|
|
El pipeline está en `.github/workflows/ci.yml` y ejecuta:
|
|
|
|
1. **CI**: Lint, test y build de todas las apps
|
|
2. **Docker Build**: Construye y publica imágenes a GHCR
|
|
3. **Deploy**: Despliega automáticamente al servidor
|
|
|
|
### Secrets Requeridos en GitHub
|
|
|
|
| Secret | Descripción |
|
|
|--------|-------------|
|
|
| `SERVER_HOST` | IP o dominio del servidor |
|
|
| `SERVER_USER` | Usuario SSH |
|
|
| `SERVER_SSH_KEY` | Llave privada SSH |
|
|
|
|
### Variables de Entorno en GitHub
|
|
|
|
| Variable | Descripción |
|
|
|----------|-------------|
|
|
| `VITE_API_URL` | URL de la API para el build |
|
|
|
|
### Configurar Secrets
|
|
|
|
```bash
|
|
# En GitHub: Settings > Secrets and variables > Actions
|
|
|
|
# SERVER_HOST
|
|
tu-servidor.com
|
|
|
|
# SERVER_USER
|
|
deploy
|
|
|
|
# SERVER_SSH_KEY
|
|
-----BEGIN OPENSSH PRIVATE KEY-----
|
|
...
|
|
-----END OPENSSH PRIVATE KEY-----
|
|
```
|
|
|
|
---
|
|
|
|
## Backups
|
|
|
|
### Backup Manual
|
|
|
|
```bash
|
|
./deploy/scripts/backup.sh
|
|
```
|
|
|
|
Los backups se guardan en `./backups/` con formato: `michangarrito_dev_YYYYMMDD_HHMMSS.sql.gz`
|
|
|
|
### Restaurar Backup
|
|
|
|
```bash
|
|
./deploy/scripts/backup.sh --restore backups/michangarrito_dev_20260107_120000.sql.gz
|
|
```
|
|
|
|
### Backup Automático (Cron)
|
|
|
|
```bash
|
|
# Agregar a crontab
|
|
0 2 * * * /opt/michangarrito/deploy/scripts/backup.sh >> /var/log/michangarrito-backup.log 2>&1
|
|
```
|
|
|
|
---
|
|
|
|
## Monitoreo
|
|
|
|
### Ver Logs
|
|
|
|
```bash
|
|
# Todos los servicios
|
|
docker-compose logs -f
|
|
|
|
# Servicio específico
|
|
docker-compose logs -f backend
|
|
docker-compose logs -f postgres
|
|
|
|
# Últimas 100 líneas
|
|
docker-compose logs --tail=100 backend
|
|
```
|
|
|
|
### Métricas de Contenedores
|
|
|
|
```bash
|
|
# Uso de recursos
|
|
docker stats
|
|
|
|
# Estado de salud
|
|
docker-compose ps
|
|
```
|
|
|
|
### Health Endpoints
|
|
|
|
| Servicio | Endpoint |
|
|
|----------|----------|
|
|
| Backend | `GET /api/v1/health` |
|
|
| Frontend | `GET /health` |
|
|
| WhatsApp | `GET /health` |
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Error: Puerto en uso
|
|
|
|
```bash
|
|
# Identificar proceso
|
|
sudo lsof -i :3141
|
|
|
|
# Matar proceso o cambiar puerto en .env
|
|
```
|
|
|
|
### Error: Container no inicia
|
|
|
|
```bash
|
|
# Ver logs detallados
|
|
docker-compose logs backend
|
|
|
|
# Reiniciar servicio
|
|
docker-compose restart backend
|
|
|
|
# Reconstruir
|
|
docker-compose up -d --build backend
|
|
```
|
|
|
|
### Error: Base de datos no conecta
|
|
|
|
```bash
|
|
# Verificar que postgres esté corriendo
|
|
docker-compose ps postgres
|
|
|
|
# Ver logs de postgres
|
|
docker-compose logs postgres
|
|
|
|
# Probar conexión
|
|
docker-compose exec postgres psql -U michangarrito_dev -d michangarrito_dev
|
|
```
|
|
|
|
### Error: Frontend no carga
|
|
|
|
```bash
|
|
# Verificar build
|
|
docker-compose logs frontend
|
|
|
|
# Verificar nginx
|
|
docker-compose exec frontend cat /etc/nginx/conf.d/default.conf
|
|
|
|
# Reiniciar
|
|
docker-compose restart frontend
|
|
```
|
|
|
|
### Limpiar Todo y Reiniciar
|
|
|
|
```bash
|
|
# Detener todo
|
|
docker-compose down -v
|
|
|
|
# Limpiar imágenes
|
|
docker system prune -af
|
|
|
|
# Reconstruir desde cero
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
---
|
|
|
|
## Comandos Útiles
|
|
|
|
```bash
|
|
# Iniciar servicios
|
|
docker-compose up -d
|
|
|
|
# Detener servicios
|
|
docker-compose down
|
|
|
|
# Reconstruir un servicio
|
|
docker-compose up -d --build backend
|
|
|
|
# Entrar a un contenedor
|
|
docker-compose exec backend sh
|
|
|
|
# Ejecutar comando en contenedor
|
|
docker-compose exec postgres psql -U michangarrito_dev
|
|
|
|
# Ver uso de disco
|
|
docker system df
|
|
|
|
# Limpiar recursos no usados
|
|
docker system prune -f
|
|
```
|
|
|
|
---
|
|
|
|
## Arquitectura de Despliegue
|
|
|
|
```
|
|
┌─────────────┐
|
|
│ INTERNET │
|
|
└──────┬──────┘
|
|
│
|
|
┌──────▼──────┐
|
|
│ NGINX │
|
|
│ :80/:443 │
|
|
└──────┬──────┘
|
|
│
|
|
┌────────────────────┼────────────────────┐
|
|
│ │ │
|
|
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
|
│ FRONTEND │ │ BACKEND │ │ WHATSAPP │
|
|
│ :80 │ │ :3141 │ │ :3143 │
|
|
└─────────────┘ └──────┬──────┘ └─────────────┘
|
|
│
|
|
┌────────────────┼────────────────┐
|
|
│ │ │
|
|
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
|
│ POSTGRES │ │ REDIS │ │ (otros) │
|
|
│ :5432 │ │ :6379 │ │ │
|
|
└─────────────┘ └─────────────┘ └─────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
**Documento generado**: 2026-01-07
|