Preparar bundle remoto de documentación
Prepara el contenido que consumen las rutas de Docs. Con una ref DOCS configurada, descarga el repositorio remoto, sincroniza artículos y assets, y escribe articles.json y manifest.json. Sin ref configurada, conserva el contenido local existente y termina correctamente.
En este artículo
Esta guía sirve para operadores de release y responsables de build que necesitan dejar listo el bundle de documentación antes de empaquetar el backend. La acción no se ejecuta desde la app ni desde una API: es un paso operativo de shell.
El resultado lo consume después la API de Docs, tanto en /api/public/docs como en /api/app/docs. La pantalla Docs de Antylogic solo valida que el runtime lee el bundle ya preparado.
Antes de empezar
- Ejecutar desde backend o desde un cwd equivalente donde exista scripts/sync-docs-content.mjs.
- Tener sh, git y node disponibles en el entorno de build.
- Garantizar escritura sobre DOCS_CONTENT_OUTPUT, DOCS_ASSETS_OUTPUT y DOCS_CHECKOUT_DIR.
- Definir una ref si se quiere regenerar contenido remoto: DOCS_REF_DEPLOY_<ENV>, DOCS_REF_DEPLOY, DOCS_VERSION_DEPLOY_<ENV> o DOCS_VERSION.
- Para repositorios privados, aportar DOCS_REPOSITORY_URL o credenciales GitLab compatibles.
Instrucciones
- 1.
Confirmar el entorno de ejecución
Entrar en backend y comprobar que el proceso puede ejecutar shell, git y node. Si no se pasa entorno al script, usa DEPLOY_ENV y después dev.
- 2.
Definir ref y versión DOCS
Decidir qué contenido debe quedar embebido. La ref se resuelve con prioridad por entorno: DOCS_REF_DEPLOY_<ENV>, DOCS_REF_DEPLOY, DOCS_VERSION_DEPLOY_<ENV> y DOCS_VERSION. La versión visible usa DOCS_VERSION_DEPLOY_<ENV>, DOCS_VERSION y finalmente la ref.
- 3.
Configurar acceso al repositorio
Cuando hay ref, el script usa DOCS_REPOSITORY_URL si está definida. Si no, construye una URL GitLab con token compatible, CI_JOB_TOKEN o la URL pública del proyecto docs.
- 4.
Ejecutar la preparación
Lanzar scripts/prepare-docs-content.sh [environment]. Con ref remota, el script crea un checkout temporal, hace fetch --depth 1, checkout detached de FETCH_HEAD y ejecuta sync-docs-content.mjs con las rutas y metadatos DOCS.
- 5.
Revisar el contenido generado
Comprobar que DOCS_CONTENT_OUTPUT contiene articles.json y manifest.json. El manifest debe registrar versión, fecha de generación, fuente, proyecto, ref, locales, plataformas y raíces de assets.
- 6.
Empaquetar en runtime
Verificar que el build backend copia docs-content y docs-assets ya preparados. Los Dockerfiles no regeneran el bundle; solo fijan DOCS_CONTENT_PATH, DOCS_ASSETS_PATH y ANTYLOGIC_DOCS_VERSION.
- 7.
Verificar la API de Docs
Tras levantar o desplegar el runtime, comprobar /api/public/docs sin autenticación y /api/app/docs con sesión autenticada. En el demo ES puede usarse Grupo Marea Demo para validar la pantalla Docs, pero la preparación del bundle es global.
- 8.
Gestionar casos alternativos
Si no hay ref DOCS, el resultado correcto es conservar el contenido local. Si el checkout remoto funciona pero falla el sync, DOCS_ALLOW_LOCAL_FALLBACK puede conservar articles.json local según su valor.
Validaciones y límites
- DOCS_CHECKOUT_DIR no puede ser vacío, /, . ni ...
- git fetch y git checkout deben completarse; los fallos de red o autenticación abortan antes del fallback local.
- La fuente remota debe incluir una ruta soportada, como docs-content/articles.json, articles.json o wiki-generated-data.ts.
- articles.json debe ser un array o un objeto con articles array.
- Si la fuente es TypeScript, debe contener generatedWikiGuideData con el terminador esperado.
- DOCS_ASSETS_OUTPUT se resetea antes de copiar assets cuando el sync lo recibe.
- Sin articles.json, la API consumidora responde 503 documentación no configurada; si no puede decodificarlo, responde 500 documentación no disponible.
- Las rutas de assets limpian la ruta solicitada y rechazan traversal antes de servir archivos desde DOCS_ASSETS_PATH.
- /api/version expone docs.version desde ANTYLOGIC_DOCS_VERSION, que puede diferir de articles.json.version si el build recibe otra versión.
Resultado esperado
El runtime queda con un bundle de Docs preparado o conservado localmente. Las rutas públicas y autenticadas de documentación pueden leer el mismo contenido, servir assets desde DOCS_ASSETS_PATH y exponer la versión operacional en /api/version.