# 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= # 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= # JWT con secret largo JWT_SECRET= # 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