Saltar a contenido

Documento histórico — ya ejecutado. El upgrade a Medusa 2.15.5 está aplicado en todas las ramas publicadas desde a1c6ba9 (2026-06-18). Se conserva como registro del procedimiento seguido. Para operar el sistema hoy, usar el runbook; el registry real es GHCR (ghcr.io/compulandiati/ecommercev2backend), no el sirhugh/medusa-backend que menciona este plan.

Plan de despliegue: upgrade Medusa 2.11.3 → 2.15.5

Objetivo: desplegar a producción el upgrade a 2.15.5 (validado en dev), sin tocar la arquitectura (workerMode: "shared" se mantiene; el split va después). Se simula primero en staging, máquina espejo de prod donde el proyecto se compila y dockeriza igual que en producción.

1. Qué se despliega (cambios de esta tanda)

Todo en la rama upgrade/medusa-2.15.5:

Archivo Cambio
package.json 5 paquetes @medusajs/* → 2.15.5
package-lock.json Regenerado (npm)
yarn.lock Eliminado (lockfile unificado a npm)
src/api/store/bancard-qr/generate/route.ts Fix TS display_id (cast unknown)
src/admin/components/price-list-variant/hooks/useVariantsLoader.ts Fix regresión: variantes del price list vía products?price_list_id
src/admin/components/price-list-variant/utils.ts Inventario en lotes de 100 (stock para >100 variantes)

Validado en dev: build ✅ · migraciones 147→170 con datos intactos ✅ · smoke admin/store/custom/bancard ✅ · widget de price list ✅.

2. Contexto de despliegue (cómo llega a prod)

  • Dev usa build: . (compila local).
  • Prod/staging corren una imagen de registry (sirhugh/medusa-backend:<tag>).
  • El Dockerfile (multi-stage): builder con npm install + medusa build → runner con npm ci --omit=dev sobre .medusa/server → arranca start.sh.
  • start.sh en el arranque ejecuta: db:migrate → seed → crea admin → medusa start. → Las migraciones del upgrade se aplican solas al levantar el contenedor.

Implicación clave: el backup de DB antes de levantar el contenedor nuevo es obligatorio, porque las migraciones corren automáticamente en el boot.

3. Decisiones a cerrar antes de desplegar

# Decisión Opciones Recomendación
U1 Tag de la imagen nueva (a) 1.1.0; (b) otro (a) — y conservar 1.0.1 para rollback.
U2 npm run seed en start.sh (a) Quitarlo ahora; (b) dejarlo (a) — en prod no debe correr en cada boot. Ya que tocamos el deploy, sacarlo. Cambio independiente del split.
U3 Creación de admin en start.sh (a) Quitar, crear manual; (b) dejar con \|\| true (b) tolerable (ya tiene \|\| true); (a) más limpio.
U4 AUTH_MFA_ENCRYPTION_KEY (a) Añadir a .env (64 chars); (b) omitir (a) — defensivo, por si el Auth Module la exige.
U5 Dónde se construye la imagen (a) En staging/CI y push al registry; (b) build local y push Según tu flujo actual. Confirmar quién tiene acceso al registry sirhugh/....
U6 Datos en staging (a) Copia de la DB de prod (ideal, prueba migraciones reales); (b) datos de staging (a) — para validar migraciones + el widget con >100 variantes.

4. Simulación en STAGING (espejo de prod)

4.1 Preparación

  1. Llevar la rama upgrade/medusa-2.15.5 a staging (push + checkout, o el mecanismo que uses).
  2. Aplicar decisiones U2/U4 si se aprueban (editar start.sh y .env de staging).
  3. (U6) Cargar en la DB de staging una copia reciente de prod (pg_dump/pg_restore).
  4. Backup de esa DB de staging antes de levantar (para repetir la prueba).

4.2 Build + dockerización (igual que prod)

  1. Construir la imagen: docker compose build (o docker build -t sirhugh/medusa-backend:1.1.0 .).
  2. Checkpoint: el paso npm ci --omit=dev del runner debe completar sin error (deps cambiaron). Si falla por desajuste lock/.medusa/server/package.json, revisar antes de seguir.
  3. Checkpoint: medusa build debe terminar con admin + backend OK (como en dev).
  4. Levantar: docker compose up -d.
  5. En el boot, start.sh corre db:migrate → debe aplicar las 23 migraciones + 3 scripts de datos sin error (verificar en logs).

4.3 Smoke test en staging (criterios de aceptación)

  • [ ] Contenedor Up, sin reinicios; logs sin errores de arranque.
  • [ ] Migraciones aplicadas (log "Migration scripts completed").
  • [ ] GET /health → 200.
  • [ ] Login admin OK; dashboard carga.
  • [ ] Listado y edición de productos.
  • [ ] Widget de price list: abrir una lista con >100 variantes → se muestran todas + stock correcto.
  • [ ] Los otros 5 widgets del admin cargan.
  • [ ] Store: /store/products, ruta custom /store/custom/products/:id.
  • [ ] Pagos: flujo Bancard QR (ruta parchada) y transferencia.
  • [ ] Emails (notificaciones) salen.
  • [ ] Jobs programados (incl. bancard-qr-cleanup) se registran sin error.

Si todo pasa en staging → proceder a prod replicando exactamente la imagen y los pasos.

5. Despliegue a PRODUCCIÓN

  1. Ventana de mantenimiento (habrá reinicio + migraciones).
  2. Backup de la DB de prod (pg_dump -Fc) — guardarlo fuera del contenedor. Bloqueante.
  3. Anotar el tag de imagen actual en uso (1.0.1) para rollback.
  4. Desplegar la imagen 1.1.0 (misma que se validó en staging — push al registry y pull en prod, o como corresponda).
  5. docker compose up -d → start.sh aplica migraciones en el boot. Vigilar logs de migración.
  6. Smoke test en prod (misma checklist de 4.3, foco en pagos y widget).
  7. Monitoreo post-deploy: dejar el monitor de capas durante el primer resync del integrador y comparar con la línea base.

6. Backup y rollback

Escenario Acción
Build falla en staging No afecta prod; corregir y reconstruir.
Migraciones fallan en boot Contenedor no sirve tráfico correctamente → restaurar DB del backup + volver a imagen 1.0.1.
Bug funcional en prod tras deploy Volver a imagen 1.0.1 y restaurar el backup de DB (las migraciones 2.15 dejan el schema adelante de 2.11; el código viejo no corre contra schema nuevo → rollback de código exige rollback de DB).

⚠️ Regla de oro del rollback: código e imagen viejos requieren la DB del backup. No se puede correr 2.11.3 contra un schema ya migrado a 2.15. Por eso el backup pre-deploy es la pieza crítica.

7. Riesgos y notas

Riesgo / nota Mitigación
npm ci --omit=dev falla en el runner por cambio de deps Verificar en el build de staging (checkpoint 4.2.5).
Migraciones irreversibles Backup obligatorio; probadas ya en dev (147→170 OK).
Build del admin (React/icons) Ya validado en dev (React 18 compatible).
seed en cada boot (si no se quita, U2) Quitar de start.sh.
Redis: prod usa redis:7-alpine OK (el warning de 6.0.16 es solo del dev local).
Node: Dockerfile node:20-alpine OK (2.15.5 requiere >=20).
Vulnerabilidades npm audit Informativas; no correr --force ahora.

8. Próximos pasos

  1. Cerrar decisiones U1–U6 (sobre todo U2, U4, U6).
  2. Commitear la rama upgrade/medusa-2.15.5 (todo junto, como se acordó).
  3. Ejecutar la simulación en staging (sección 4).
  4. Si pasa → producción (sección 5).
  5. Después del upgrade estabilizado → retomar el split server/worker (ver docs/medusa-split-deployment-plan.md).