⚠ Vigencia por confirmar. Documento previo al estándar de documentación, migrado sin reescribir su contenido técnico. Revisar contra el código antes de usarlo como fuente de verdad.

Despliegue de EcommerceV2Backend¶

Guía específica de despliegue para el proyecto EcommerceV2Backend en staging y producción.

Para la configuración genérica del CI/CD, ver: CI/CD con runners self-hosted

Arquitectura del Proyecto¶

graph TB
    subgraph GitHub["GitHub Repository"]
        Repo["CompulandiaTI/EcommerceV2Backend"]
        Main["Main Branch"]
        Staging["Staging Branch"]
    end

    subgraph GitHub_Actions["GitHub Actions CI"]
        Build["Build Job<br/>(ubuntu-latest)"]
    end

    subgraph GHCR["GitHub Container Registry"]
        Images["ghcr.io/compulandiati/ecommercev2backend"]
        StagingTag["staging-sha-*<br/>staging-latest"]
        ProdTag["sha-*<br/>latest"]
    end

    subgraph Staging_Env["Staging Environment"]
        RunnerS["Runner Self-Hosted<br/>(staging label)"]
        DockerS["Docker Compose"]
        MedusaS["Medusa Backend<br/>/home/hquintero/ecommerce/backend"]
    end

    subgraph Production_Env["Production Environment"]
        RunnerP["Runner Self-Hosted<br/>(production label)"]
        DockerP["Docker Compose"]
        MedusaP["Medusa Backend<br/>/home/hquintero/ecommerce/backend"]
    end

    Staging -->|Auto-push| Build
    Main -->|Manual push| Build

    Build -->|Build staging tags| StagingTag
    Build -->|Build prod tags| ProdTag

    StagingTag -->|Auto-deploy| RunnerS
    ProdTag -->|Manual deploy| RunnerP

    RunnerS -->|docker compose up| DockerS
    DockerS -->|runs| MedusaS

    RunnerP -->|docker compose up| DockerP
    DockerP -->|runs| MedusaP

    style Staging fill:#90EE90
    style Production fill:#FFB6C6

Flujo de Despliegue¶

Staging: Automático en cada push¶

sequenceDiagram
    participant Dev as Developer
    participant Repo as GitHub Repo
    participant CI as GitHub Actions
    participant Runner as Runner Staging
    participant Server as Staging Server

    Dev->>Repo: git push origin staging
    Repo->>CI: Trigger workflow
    CI->>CI: Build image<br/>staging-sha-abc123
    CI->>CI: Push to GHCR
    CI->>Runner: Dispatch deploy-staging
    Runner->>Server: cd /home/hquintero/ecommerce/backend
    Runner->>Server: export MEDUSA_TAG=staging-sha-abc123
    Runner->>Server: ./deploy.sh
    Server->>Server: Backup BD + Deploy + Health Check
    Server-->>Dev: ✅ Despliegue OK

Production: Manual con workflow_dispatch¶

sequenceDiagram
    participant Dev as Developer
    participant GitHub as GitHub UI
    participant CI as GitHub Actions
    participant Runner as Runner Production
    participant Server as Production Server

    Dev->>GitHub: Run workflow
    GitHub->>GitHub: Select: production environment
    GitHub->>CI: workflow_dispatch triggered
    CI->>CI: Build image (sha-abc123)
    CI->>CI: Push to GHCR
    CI->>Runner: Dispatch deploy-prod
    Runner->>Server: cd /home/hquintero/ecommerce/backend
    Runner->>Server: export MEDUSA_TAG=sha-abc123
    Runner->>Server: ./deploy.sh
    Server->>Server: Backup BD + Deploy + Health Check
    Server-->>Dev: ✅ Despliegue OK

Información del Proyecto¶

Concepto	Valor
Repository	`CompulandiaTI/EcommerceV2Backend`
Staging Directory	`/home/hquintero/ecommerce/backend`
Production Directory	`/home/hquintero/ecommerce/backend`
Image Repository	`ghcr.io/compulandiati/ecommercev2backend`
Staging Runner Label	`staging`
Production Runner Label	`production`
Staging Deployment	Automático (push a staging)
Production Deployment	Manual (workflow_dispatch en main)

Convención de Tags¶

Rama	Tag Imagen	Uso
`staging`	`staging-sha-abc123`	Commit específico en staging
`staging`	`staging-latest`	Última versión en staging
`main`	`sha-abc123`	Commit específico en producción
`main`	`latest`	Última versión en producción

Cómo Deployar¶

Staging: Automático¶

# Solo hacer push a staging
git checkout staging
git pull origin staging
# Hacer cambios...
git add .
git commit -m "feat: nueva feature"
git push origin staging

El workflow corre automáticamente: - ✅ Build imagen con tag staging-sha-abc123 - ✅ Deploy a staging automáticamente - ✅ Health check

Production: Manual¶

# 1. Asegurarse que main está actualizado
git checkout main
git pull origin main

# 2. Mergear staging (cambios probados)
git merge staging

# 3. Push a main dispara el build
git push origin main

En GitHub: 1. Ve a: Actions → Build, Test & Deploy 2. Click en "Run workflow" (dropdown) 3. Selecciona: environment: production 4. Click "Run workflow" (botón verde)

El runner de producción ejecutará el deploy automáticamente.

Estructura del Proyecto¶

/home/hquintero/ecommerce/backend/
├── .github/workflows/
│   └── build-deploy.yml          # Workflow CI/CD
├── Dockerfile                     # Multi-stage build
├── docker-compose.yml             # Define servicios
├── deploy.sh                      # Script de despliegue
├── .env                          # Credenciales (git-ignored)
├── backups/                      # Backups de BD (generados)
├── CI_CD_SETUP.md                # Guía genérica (para wiki)
└── DEPLOYMENT_ECOMMERCE.md       # Este archivo

Variables de Entorno (.env)¶

El archivo .env no está trackeado en git (por seguridad). Debe existir en el servidor.

En /home/hquintero/ecommerce/backend/.env:

DATABASE_URL=postgres://<usuario>:<password>@postgres:5432/medusa-store
REDIS_URL=redis://redis:6379

Deploy Script (deploy.sh)¶

El script realiza:

Backup: pg_dump de la BD actual
Captura: Guarda imagen actual para rollback
Pull + Up: Descarga nueva imagen y levanta contenedores
Health Check: Verifica que la app esté healthy
Auto-rollback: Si falla, revierte automáticamente

Rollback Manual¶

# En el servidor de producción
cd /home/hquintero/ecommerce/backend

# Rollback a una versión anterior
export MEDUSA_TAG="sha-def456"
./deploy.sh

Tags disponibles: Ve a GitHub → Code → Packages

Verificación Post-Deploy¶

1. Verificar que el contenedor está corriendo¶

cd /home/hquintero/ecommerce/backend
docker compose ps

Deberías ver 3 contenedores en estado "Up": - medusa_postgres - medusa_redis - medusa_backend

2. Verificar health check¶

curl http://localhost:9000/health

Debería responder {"status":"ok"} o similar.

3. Ver logs¶

docker compose logs medusa

4. Verificar imagen desplegada¶

docker ps --format "table {{.Names}}\t{{.Image}}"

Debería mostrar: medusa_backend | ghcr.io/compulandiati/ecommercev2backend:sha-abc123

Troubleshooting¶

Deploy falla con "CD /opt/medusa: No such file or directory"¶

Problema: El workflow está usando una ruta incorrecta.

Solución: El directorio del proyecto debe estar en /home/hquintero/ecommerce/backend. Si el error persiste, revisar el workflow en .github/workflows/build-deploy.yml.

Deploy falla con "Database URL variable is not set"¶

Problema: El archivo .env no existe o no tiene DATABASE_URL.

Solución:

cd /home/hquintero/ecommerce/backend
cat .env  # Verificar que existe
# Si no existe, crear:
echo "DATABASE_URL=postgres://<usuario>:<password>@postgres:5432/medusa-store" >> .env
echo "REDIS_URL=redis://redis:6379" >> .env

Health check falla¶

Problema: La aplicación no inicia correctamente.

Solución:

# Ver logs detallados
docker compose logs medusa | tail -100

# Verificar que postgres está corriendo
docker compose logs postgres | tail -20

# Verificar que redis está corriendo
docker compose logs redis | tail -20

# Si postgres/redis no están, subirlos:
docker compose up -d postgres redis

Runner no ejecuta el job¶

Problema: El job en GitHub Actions dice "Waiting for a runner to pick up this job..."

Solución:

# Verificar que el runner está online en GitHub
# GitHub → Settings → Actions → Runners

# En el servidor, verificar que el runner está corriendo:
sudo systemctl status actions-runner

# Ver logs:
sudo journalctl -u actions-runner -f

# Si está offline, reiniciar:
sudo systemctl restart actions-runner

Logs Importantes¶

GitHub Actions¶

Logs de build: GitHub → Actions → Workflow run → build job
Logs de deploy: GitHub → Actions → Workflow run → deploy-staging/deploy-prod

Servidor¶

# Logs del runner
sudo journalctl -u actions-runner -f

# Logs de la aplicación
docker compose logs medusa -f

# Logs de backups
ls -lah /home/hquintero/ecommerce/backend/backups/

Checklists¶

Antes de hacer deploy a producción¶

[ ] Cambios probados en staging
[ ] Tests pasan
[ ] Health check pasó en staging
[ ] Backup manual disponible

Después de deploy a producción¶

[ ] docker compose ps muestra 3 contenedores en "Up"
[ ] curl http://localhost:9000/health responde OK
[ ] docker compose logs medusa no muestra errores críticos
[ ] Verificar que la versión desplegada es la correcta

Rollback Rápido¶

Si algo sale mal en producción:

# 1. SSH al servidor de producción
ssh hquintero@PROD_IP

# 2. Ir al directorio
cd /home/hquintero/ecommerce/backend

# 3. Ejecutar deploy con tag anterior
export MEDUSA_TAG="sha-PREVIOUS_SHA"
./deploy.sh

# 4. Verificar
docker compose logs medusa | tail -20
curl http://localhost:9000/health

Contacto y Escalada¶

Para problemas con: - Workflow/CI/CD: Revisar GitHub Actions logs - Runner offline: SSH al servidor y revisar systemd logs - Deploy falla: Ver logs de aplicación en servidor - Performance: Revisar logs de postgres/redis

¿Preguntas sobre el despliegue de este proyecto?