Runbook — Despliegue del token INTERNAL_TOOLS_TOKEN (endpoint openapi-export)

Propósito

Activar el endpoint GET /api/openapi-export en PROD y STAGE configurando el token Bearer INTERNAL_TOOLS_TOKEN. Sin este token, el endpoint devuelve 401 deny-all y el cron bib-reindex omite la indexación OpenAPI.

Este runbook cubre el despliegue inicial (post-merge s50). Para rotación de token, seguir los mismos pasos con un token nuevo.

Requisitos previos

Acceso SSH a STAGE (host donde corre cron-bib-reindex.sh).
Acceso al panel Dokploy con permisos de edición de variables de entorno de la app crearack-pro.
Python 3 disponible en la máquina local para generar el token.

Pasos

1. Generar el token

python -c "import secrets; print(secrets.token_urlsafe(48))"

Guarda el resultado — es el <TOKEN>. Debe tener ≥32 caracteres (el endpoint rechaza tokens más cortos).

2. Configurar en PROD (Dokploy)

Ir a Dokploy → app crearack-pro → Variables de entorno.
Añadir o actualizar: INTERNAL_TOOLS_TOKEN=<TOKEN>
Hacer redeploy para que el container web tome la variable.

3. Configurar en STAGE (archivo de token del cron)

# En el host STAGE (SSH):
echo "<TOKEN>" > /opt/bib-reindex/.token-internal
chmod 600 /opt/bib-reindex/.token-internal
# Verificar:
ls -la /opt/bib-reindex/.token-internal
# Debe mostrar: -rw------- 1 <user> ...

El script cron-bib-reindex.sh --extras-only lee este archivo y exporta INTERNAL_TOOLS_TOKEN antes de llamar a bib_openapi.py.

4. Verificar el endpoint

# Con el token configurado en PROD:
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer <TOKEN>" \
  https://crearack.com/api/openapi-export
# Debe responder 200

Si responde 401: verificar que el token en Dokploy coincide exactamente con el usado en el curl (sin espacios, sin salto de línea).

5. Test del cron en STAGE

# En el host STAGE, como el usuario del cron:
/opt/bib-reindex/cron-bib-reindex.sh --extras-only

Comprobar que en los logs no aparece "saltando openapi" y que bib_openapi.py reporta éxito al postear al MCP.

6. Añadir entrada al cron

# En /etc/cron.d/bib-reindex (STAGE):
30 * * * * <user> /opt/bib-reindex/cron-bib-reindex.sh --extras-only >> /var/log/bib-reindex.log 2>&1

Errores comunes

Error	Causa	Solución
HTTP 401	Token no configurado, vacío o <32 chars	Revisar variable en Dokploy y redeploy
`Token interno vacio, saltando openapi`	`.token-internal` vacío o con solo newline	`echo "<TOKEN>" > ...` y verificar con `cat`
`$DIR/.token-internal no legible`	Permisos incorrectos o archivo no existe	`chmod 600` y verificar existencia
rc=137 (docker exec)	OOM en host con poca RAM	Este runbook resuelve eso: usar modo HTTP
Conexión rechazada	PROD no alcanzable desde STAGE	Verificar DNS / firewall / que PROD esté up

Rotación del token

Repetir pasos 1→5. El redeploy de Dokploy y la actualización de .token-internal deben hacerse de forma coordinada para evitar ventana de 401.

Véase también

[[entity—api—endpoint—openapi-export]]
[[entity—api—script—bib-openapi]]
[[feature—biblioteca—bib-openapi-http-mode]]