Runbook — OMS Backend¶

Deploy¶

Dónde corre: contenedor Docker oms-backend (puerto interno 7000) en el servidor de cada ambiente, orquestado desde el repo oms-deployment en /opt/oms-<ambiente>/. La imagen vive en GHCR (ghcr.io/compulandiati/oms-ventas-backend). Nginx del host proxea el tráfico e incluye el upgrade de WebSocket. Redis corre nativo en el host.

Staging (automático): el push a la rama de staging construye la imagen en GitHub Actions (tags :staging y :staging-<sha>) y el runner del servidor ejecuta ./deploy.sh backend, con rollback automático si el healthcheck falla.

Producción (manual, después de validar staging):

ssh <servidor-produccion>
cd /opt/oms-production
./deploy.sh backend            # baja la última imagen :production y redeploya

Cómo verificar que el deploy salió bien:

docker compose ps                          # backend en estado "healthy"
curl -s http://localhost:7000/api/health   # respuesta 200
docker compose logs backend --tail=50      # sin errores de arranque

Logs¶

Qué	Dónde	Cómo verlos
Aplicación	contenedor `oms-backend`	`docker compose logs -f backend`
Errores agregados	GlitchTip	buscar por tag `request_id` (el `referenceId` que devuelve la API)
Correlación	prefijo `[rid:…]` en logs	`docker compose logs backend \\| grep <request-id>`

Variables de entorno¶

Runtime por ambiente: envs/<ambiente>/backend.env en el servidor (templates backend.env.example en el repo oms-deployment).
Local: .env en la raíz del repo — pedir uno de referencia al equipo.
Antes de tocar un .env del servidor correr ./check-env.sh: Docker parsea más estricto que dotenv (sin comillas, sin comentarios inline, escapar $).

Rollback¶

El deploy guarda el SHA desplegado en .deploy-state-backend. Si un deploy falla el healthcheck, deploy.sh vuelve solo a la versión previa. Para un rollback manual a un SHA conocido:

cd /opt/oms-production
./deploy.sh backend <sha>      # despliega ghcr.io/.../oms-ventas-backend:production-<sha>

No hay migraciones de base de datos propias (los datos viven en SAP), así que el rollback de imagen no tiene precondiciones.

Fallas frecuentes¶

1. `[ioredis] connect ECONNREFUSED` — el backend no llega a Redis¶

Diagnóstico: docker compose logs backend --tail=50. Si el error apunta a 127.0.0.1:6379, el REDIS_HOST del backend.env está mal (dentro del contenedor 127.0.0.1 es el contenedor mismo). Si apunta a 172.17.0.1:6379, Redis del host está bindeado solo a 127.0.0.1.
Resolución:

# Caso 127.0.0.1: apuntar al gateway del host
sed -i 's|^REDIS_HOST=.*|REDIS_HOST=host.docker.internal|' envs/<ambiente>/backend.env
docker compose restart backend
# Caso 172.17.0.1: bindear Redis del host a 0.0.0.0 y bloquear el puerto por firewall

2. Certificados: `EACCES: permission denied, open 'certs/…'` o `Fallo al cargar el certificado PFX`¶

Diagnóstico: comparar lo que hay montado contra lo que el env espera:

docker exec oms-backend ls -la /app/certs/
grep -E 'CONTINENTAL_CERT_PATH|NODE_EXTRA_CA_CERTS' envs/<ambiente>/backend.env

Resolución: si es EACCES, el contenedor (UID 1001) no puede leer archivos del host con permisos 600: chmod 644 certs/*.pfx certs/*.pem. Si es "Fallo al cargar PFX", el nombre del archivo no coincide con CONTINENTAL_CERT_PATH — renombrar o corregir el env y reiniciar.

3. SSO roto: `openid-client: unexpected HTTP response status code` en el callback¶

Diagnóstico: el Keycloak interno usa un certificado firmado por una CA que Node no conoce. Confirmar con docker compose logs backend | grep openid.
Resolución: montar la CA y declararla en el compose del backend: NODE_EXTRA_CA_CERTS=/app/certs/sso_ca.pem, con sso_ca.pem presente en deployment/certs/ y permisos 644. Reiniciar el backend.

Más casos (build de CI, sintaxis de .env, healthchecks colgados) en el troubleshooting de oms-deployment.