michangarrito/backups/docs-backup-2026-01-10/docs/90-transversal/GUIA-DESPLIEGUE.md

Guía de Despliegue - MiChangarrito

Versión: 1.0.0 Última actualización: 2026-01-07 Autor: @PERFIL_DEVOPS

---

Tabla de Contenidos

1. Requisitos
2. Despliegue Local (Docker)
3. Despliegue en Producción
4. CI/CD con GitHub Actions
5. Configuración de SSL
6. Backups
7. Monitoreo
8. 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

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

# 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

git clone https://github.com/isem/michangarrito.git
cd michangarrito

2. Configurar Variables de Entorno

# Copiar template
cp .env.docker .env

# Editar con tus credenciales
nano .env

Variables importantes a configurar:

# 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

# Usando el script de deploy
./deploy/scripts/deploy.sh

# O directamente con docker-compose
docker-compose up -d

4. Verificar Estado

# 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

# 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

cp .env.docker .env
nano .env

Configuración de producción:

# 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

# 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

./deploy/scripts/deploy.sh --production --build

6. Configurar Renovación Automática de SSL

# 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

# 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

./deploy/scripts/backup.sh

Los backups se guardan en ./backups/ con formato: michangarrito_dev_YYYYMMDD_HHMMSS.sql.gz

Restaurar Backup

./deploy/scripts/backup.sh --restore backups/michangarrito_dev_20260107_120000.sql.gz

Backup Automático (Cron)

# Agregar a crontab
0 2 * * * /opt/michangarrito/deploy/scripts/backup.sh >> /var/log/michangarrito-backup.log 2>&1

---

Monitoreo

Ver Logs

# 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

# 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

# Identificar proceso
sudo lsof -i :3141

# Matar proceso o cambiar puerto en .env

Error: Container no inicia

# 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

# 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

# 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

# Detener todo
docker-compose down -v

# Limpiar imágenes
docker system prune -af

# Reconstruir desde cero
docker-compose up -d --build

---

Comandos Útiles

# 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