Preparar el bundle de Docs para el despliegue
Prepara el bundle de documentación que se empaqueta en una imagen del backend de la API REST o de Lambda, y después verifica que el runtime desplegado puede leerlo a través de la API de Docs.
En este artículo
Usa esta guía cuando un operador de release necesite empaquetar el contenido de Docs soportado más reciente en una imagen del backend antes del despliegue.
El paso de preparación es una operación de tiempo de build. Resuelve una ref de docs, opcionalmente hace checkout de un repositorio externo de docs, convierte la fuente soportada en `docs-content` y `docs-assets`, y deja el contenido local en su sitio solo bajo las reglas de fallback implementadas.
La prueba de runtime más clara es la respuesta de la API de Docs: `GET /api/public/docs?locale=es-ES&platform=web` debe devolver los metadatos del bundle, las secciones y un locale resuelto `es`.
Antes de empezar
- Ejecuta la preparación desde el directorio de trabajo de build del backend, donde `scripts/prepare-docs-content.sh`, `scripts/sync-docs-content.mjs`, `docs-content` y `docs-assets` son relativos al contexto de build de Docker.
- Cuando hay una ref de docs configurada, confirma que `git` y `node` están disponibles en el job de build.
- Elige la fuente de docs antes de construir: usa `DOCS_REF_DEPLOY_<ENV>`, `DOCS_REF_DEPLOY`, `DOCS_VERSION_DEPLOY_<ENV>`, `DOCS_VERSION`, o un `docs-content/articles.json` local existente solo donde las reglas de fallback lo permitan.
- Para repositorios de docs privados, proporciona `DOCS_REPOSITORY_URL` o credenciales de GitLab mediante las variables de token soportadas.
- Confirma que `DOCS_CHECKOUT_DIR`, `DOCS_CONTENT_OUTPUT` y `DOCS_ASSETS_OUTPUT` son escribibles y seguros para que el job de build los recree.
Instrucciones
- 1.
Selecciona el entorno de despliegue y la ref de docs
Fija `DEPLOY_ENV` para el build de la imagen. El script de preparación pasa el entorno a mayúsculas y resuelve la ref de docs desde `DOCS_REF_DEPLOY_<ENV>`, `DOCS_REF_DEPLOY`, `DOCS_VERSION_DEPLOY_<ENV>` y después `DOCS_VERSION`.
- 2.
Confirma el acceso al repositorio
Usa `DOCS_REPOSITORY_URL` cuando deba controlarse el repositorio fuente exacto. En caso contrario, el script construye una URL de GitLab a partir de `DOCS_PROJECT_DEPLOY` y de las variables de token disponibles, cayendo a una URL pública de GitLab sin autenticar.
- 3.
Ejecuta la preparación antes del build de la imagen
Deja que el job de imagen del backend ejecute `scripts/prepare-docs-content.sh "$ENV_NAME"` antes de `docker build`. Con una ref de docs, el script recrea `DOCS_CHECKOUT_DIR`, hace checkout de la ref seleccionada y delega la conversión en `node scripts/sync-docs-content.mjs`.
- 4.
Revisa las salidas generadas
Comprueba `DOCS_CONTENT_OUTPUT/articles.json` y `DOCS_CONTENT_OUTPUT/manifest.json`. El bundle generado registra la versión, los metadatos de la fuente, los locales derivados, las plataformas `mobile`, `tablet` y `web`, los artículos y los metadatos de la raíz de assets.
- 5.
Gestiona el fallback de forma deliberada
Si la conversión falla después del checkout, usa `DOCS_ALLOW_LOCAL_FALLBACK` solo cuando sea aceptable publicar el bundle local existente. El fallback `auto` por defecto solo aplica a las refs `master` y `main`; las refs fijadas requieren un valor de fallback explícitamente verdadero.
- 6.
Empaqueta la imagen del backend
Construye la imagen de la API REST o de Lambda solo después de que la preparación haya terminado o haya caído en fallback intencionadamente. Los Dockerfiles copian `docs-content` y `docs-assets` a la imagen de runtime y fijan las rutas de contenido y assets de docs.
- 7.
Verifica la API de Docs desplegada
Abre primero `GET /api/public/docs?locale=es-ES&platform=web`. Usa el usuario demo solo para la comprobación autenticada en `GET /api/app/docs?locale=es-ES&platform=web`; ambas rutas leen el mismo bundle preparado.
Validaciones y límites
- Si no hay ref de docs configurada, el script debe terminar correctamente y dejar `docs-content` local en su sitio sin regenerar el bundle.
- `DOCS_CHECKOUT_DIR` no debe estar vacío ni ser `/`, `.` o `..` antes de que el script lo borre y lo recree.
- El conversor debe encontrar un fichero fuente soportado y producir un array articles de nivel superior.
- `manifest.json` debe apuntar a `articles.json` e incluir `asset_roots.runtime_env` como `DOCS_ASSETS_PATH`.
- Para `locale=es-ES&platform=web`, la respuesta de runtime debe informar locale `es`, platform `web`, `article_count` y `sections`.
- Un build con fallback demuestra solo que se usó el contenido local existente; no demuestra que la ref externa de docs seleccionada se convirtiera correctamente.
Resultado esperado
La imagen del backend contiene el bundle preparado `docs-content` y `docs-assets`, y el runtime desplegado puede servirlo a través de las rutas pública y autenticada de la API de Docs.