Despliegue (Runbook)

El conocimiento más caro de no tener escrito. Aquí va, destino por destino, qué se despliega solo y qué tienes que hacer a mano, con el comando exacto y cómo verificar.

Mergear a main NO despliega todo

El push a main despliega solo los tres backends (vía CI). Los frontends de Cloudflare, la app de conductores y Zoho son manuales. Olvidar el deploy del frontend después de mergear es un error recurrente — el dashboard de producción no es el que viene embebido en core-backend (ver Gotchas).

1. Backends → Railway (Automático vía CI)

.github/workflows/railway-deploy.yml corre en cada push a main y, con filtros de path, despliega solo el servicio afectado usando railway up.

Servicio Railway	Se dispara cuando cambian estos paths
core-backend	apps/core-backend/**, packages/core-shared/**, lockfile, pnpm-workspace.yaml, turbo.json, package.json, el propio workflow
rnb-drivers-api (drivers-backend)	apps/drivers-backend/**, lockfile, pnpm-workspace.yaml, turbo.json, package.json, el workflow
engine-backend	apps/engine-backend/**, el workflow

Mecánica interna del workflow (por si hay que depurarlo):

• Para core/drivers, copia el railway.toml de la app a la raíz y corre railway up --service <svc> --detach.
• El engine usa railway up --service engine-backend --detach --path-as-root apps/engine-backend y buildea por Dockerfile (Python 3.12, alembic upgrade head && uvicorn ...). Los cambios de dependencias del engine sí entran en el deploy.
• Autenticación: secret RAILWAY_TOKEN en GitHub Actions.
• Proyecto Railway rnb-logistics, env production, workspace Zelta.

Trampa de paths: core-shared no redespliega drivers

Un cambio solo en packages/core-shared/** dispara el deploy de core-backend, pero no el de drivers-backend (no está en su filtro de paths). Como ambos comparten ese schema, si un cambio de core-shared afecta a drivers, fuerza un redeploy de drivers (toca algo en apps/drivers-backend/** o redespliega a mano con railway up --service rnb-drivers-api).

Verificación / observabilidad (CLI ya autenticada localmente):

railway status --service core-backend --json
railway logs   --service rnb-drivers-api --json
railway logs   --service engine-backend --json

2. Frontends Cloudflare (Manual)

Tres frontends y el backend de clientes viven en Cloudflare Workers y no están en CI: se despliegan a mano con su script deploy:prod. Requieren wrangler autenticado (OAuth kayro.valero@rnb.la; verifica con npx wrangler whoami).

# Dashboard de operaciones (SPA Vite + worker proxy a BACKEND_URL)
pnpm --filter @rnb/dash-web deploy:prod
#   = vite build && wrangler deploy --env prod
#   Worker: frontend-dash-rnb-logistics-prod

# Portal de clientes (Next.js vía OpenNext)
pnpm --filter @rnb/clients-web deploy:prod
#   = opennextjs-cloudflare build && opennextjs-cloudflare deploy --env prod
#   Worker: frontend-clients-rnb-logistics

# Vista pública de tracking
pnpm --filter @rnb/client-tracking-view deploy:prod
#   = vite build && wrangler deploy --env prod
#   Worker: frontend-tracking-view-rnb-logistics

Verificar dash-web (tiene build-info.json):

curl -s https://frontend-dash-rnb-logistics-prod.rnbl.workers.dev/build-info.json
# -> buildHash debe ser el commit que mergeaste

Cada uno tiene también deploy:dev (Workers -dev), pero en la práctica no se usa como gate: se prueba en local y se va directo a prod. Si quieres validar en un Worker real antes, ese es el camino.

3. clients-backend → Cloudflare Worker + D1 (Manual)

Es Hono sobre Workers con base D1 (SQLite) separada. El deploy del código y las migraciones de DB son pasos distintos:

# Código
pnpm --filter @rnb/clients-backend deploy:prod
#   = wrangler deploy --env prod --minify --upload-source-maps
#   Worker: backend-clients-rnb-logistics-prod

# Migraciones D1 (¡no las aplica el deploy de código!)
pnpm --filter @rnb/clients-backend db:migrate-prod
#   = wrangler d1 migrations apply backend-clients-rnb-logistics-prod --remote --env prod

Antes de prod puedes correr db:migrate-dev / db:migrate-local para la D1 -dev o la local.

4. drivers-app → OTA con EAS Update (Manual)

Mergear el PR de la app de conductores no llega a los teléfonos. Para que el cambio llegue a campo hay que publicar un OTA (mientras sea JS-only; si cambia código nativo, requiere build):

cd apps/drivers-app
eas update --branch production --message "<tipo>(drivers-app): <resumen> (<ticket-id>)"

Publica siempre desde origin/main, nunca desde main local

El main local suele estar divergido de origin/main porque se mergean features de otros worktrees a local solo para probar (commits test(local): ... — NO push). Publicar el OTA desde main local filtraría features sin liberar y podría omitir el fix que sí está en origin.

git fetch origin
git diff --stat origin/main..main   # el fix debe estar en origin; features ajenos NO
git checkout origin/main            # las deps suelen ser idénticas → se reusa node_modules
#   ... eas update ...
git checkout main

• Canal/branch de prod: production. runtimeVersion actual: 1.2.1 — verifica con eas update:list --branch production que coincida con los builds en campo; si no coincide, el OTA no los alcanza.
• El bundle embebe EXPO_PUBLIC_DOMAIN=api-drivers.rednbluelogistics.com (API de prod) desde .env / .env.production.

5. Zoho Creator (Manual, fuera del repo)

Editar los .dg del repo NO cambia producción

apps/zoho-app es un espejo/referencia de la app de Zoho Creator (functions Deluge, forms, schedules). No es la fuente de deploy. Los cambios se hacen a mano en la consola web de Zoho Creator y, si se quiere mantener el espejo, se actualiza el repo aparte.

Implicación práctica: si un bug se arregla "en Zoho", no hay PR ni deploy en este repo. Y al revés: mucha lógica que parece faltar en el código Node en realidad vive en Zoho (ver Gotchas).

Encargado de Zoho: Cesar Iglesias. Él hace los cambios en la consola de Zoho Creator y se encarga de actualizar el espejo en el repo (apps/zoho-app). Si necesitas un cambio de lógica en Zoho (functions Deluge, forms, schedules), coordínalo con él.

6. Este manual → Cloudflare Pages (Automático)

logistics-process-manual (este sitio VitePress) se despliega solo, vía Cloudflare Pages: Pages está conectado al repo y, al mergear a main, detecta los cambios en el directorio apps/logistics-process-manual/, buildea y publica automáticamente. No hay paso manual ni está en el workflow de Railway. pnpm build:logistics-manual (vitepress build) replica ese build en local para revisar antes de mergear.

7. engine-web (sin uso)

engine-web no se usa en producción. Del motor de rutas, lo único activo es engine-backend (la API). El dashboard estático quedó como artefacto: tiene su propio railway.toml (Railpack: build = copiar public/ a dist/, start = http.server) y no está en el workflow de CI, pero no hay que desplegarlo ni mantenerlo. Si tocas algo del engine, lo relevante es el backend.

Checklist De Cierre Por Tipo De Cambio

Si tocaste…	Además de mergear, haz…
core-backend / drivers-backend / engine-backend	Nada — CI despliega. Verifica railway status/logs.
packages/core-shared (afecta a drivers)	Fuerza redeploy de rnb-drivers-api.
dash-web	deploy:prod + verificar build-info.json.
clients-web / client-tracking-view	deploy:prod del frontend.
clients-backend	deploy:prod y db:migrate-prod si hubo migración.
drivers-app	eas update --branch production desde origin/main.
Schema de DB	Aditivo → auto-migrator (server/routes.ts); no-aditivo → migrations/manual/ + railway run psql. Nunca desde drivers. Ver Migraciones.
Lógica de Zoho	Aplicar en la consola de Zoho Creator.