Empaquetar los Docs en las imágenes del backend
Empaqueta el bundle de documentación preparado de Antylogic en las imágenes del backend de la API REST y de Lambda, y después verifica que el backend desplegado sirve el mismo bundle a través de las APIs de docs pública y autenticada. Es una operación de CI y despliegue, no un flujo de la app.
En este artículo
Usa esta guía cuando los operadores de release necesiten confirmar que la documentación incluida en una imagen del backend es el bundle previsto para el runtime de ES en español.
Las imágenes REST y Lambda empaquetan los mismos directorios preparados docs-content y docs-assets, pero los exponen desde rutas de runtime distintas: /app para REST y /var/task para Lambda.
Antes de empezar
- Ejecútalo desde el contexto de build del backend después de preparar backend/docs-content y backend/docs-assets.
- Usa una pipeline orquestada de release autorizada o una pipeline de tag directo permitida bajo las reglas de backend/.gitlab-ci.yml.
- Para contenido de docs externo, configura las variables DOCS_REF_DEPLOY_<ENV>, DOCS_REF_DEPLOY, DOCS_VERSION_DEPLOY_<ENV> o DOCS_VERSION correspondientes antes de que se ejecute la pipeline.
- Para publicar la imagen REST, proporciona acceso al GitLab Container Registry de CI_REGISTRY_IMAGE/restapi. Para publicar la de Lambda, proporciona el rol OIDC de AWS, el login en ECR y acceso de push a antylogic-backend-lambda.
- Ejecuta las comprobaciones de humo de la API contra la imagen del backend desplegada que se está validando. Usa la sesión del usuario demo para las comprobaciones autenticadas de /api/app/docs.
Instrucciones
- 1.
Prepara el bundle de docs
Inicia la pipeline de release para el entorno de destino. El paso de preparación ejecuta scripts/prepare-docs-content.sh "$ENV_NAME" y crea docs-content/articles.json, docs-content/manifest.json y docs-assets cuando hay configurada una ref externa de docs. Si no hay ref de docs configurada, el build usa el bundle local ya presente y commiteado bajo backend.
- 2.
Construye la imagen de la API REST
Ejecuta backend:image:restapi:gitlab o construye Dockerfile.restapi desde backend. El build compila el servidor Go, copia /src/docs-content a /app/docs-content, copia /src/docs-assets a /app/docs-assets y fija DOCS_CONTENT_PATH y DOCS_ASSETS_PATH para el servidor de runtime.
- 3.
Construye la imagen de Lambda
Ejecuta backend:image:lambda:ecr:dev, backend:image:lambda:ecr:prod o construye Dockerfile.lambda desde backend. El build compila el bootstrap de Lambda, copia el bundle de docs preparado a /var/task/docs-content y /var/task/docs-assets, y usa ANTYLOGIC_DOCS_VERSION a partir del argumento de build DOCS_VERSION.
- 4.
Verifica el backend desplegado
Tras el despliegue, llama a GET /api/version para confirmar docs.version a nivel de imagen. Después llama a GET /api/app/docs?locale=es&platform=web&theme=light con la sesión del usuario demo y a GET /api/public/docs?locale=es&platform=web&theme=light sin sesión de la app. Ambas respuestas de índice de docs deben mostrar article_count, sections y version.
- 5.
Comprueba los assets empaquetados cuando se use media
Si el bundle desplegado referencia media, solicita un fichero conocido a través de GET /api/public/docs/assets/{path} o GET /api/app/docs/assets/{path}. Trátalo solo como prueba condicional: el directorio backend/docs-assets commiteado contiene actualmente solo .gitkeep, así que los builds solo con fallback no demuestran la disponibilidad de media en producción.
Validaciones y límites
- backend/docs-content/articles.json existe antes de que empiece el docker build.
- backend/docs-assets existe antes de que empiece el docker build, aunque solo contenga ficheros de marcador.
- La imagen REST usa /app/docs-content y /app/docs-assets; la imagen Lambda usa /var/task/docs-content y /var/task/docs-assets.
- ANTYLOGIC_DOCS_VERSION procede del argumento de build DOCS_VERSION y es independiente de la versión almacenada dentro de articles.json.
- GET /api/app/docs y GET /api/public/docs devuelven payloads reales de índice de docs, no respuestas service unavailable de documentación no configurada.
- No uses HEAD /api/public/docs ni HEAD /api/app/docs como comprobaciones de integridad del paquete porque HEAD puede devolver OK antes de cargar el bundle.
- Las peticiones de assets de docs deben permanecer dentro de DOCS_ASSETS_PATH, rechazar el recorrido de directorios, devolver 404 para ficheros ausentes y fijar el tipo de contenido a partir de la extensión cuando esté disponible.
- Los builds locales directos de Docker no ejecutan sync-docs-content.mjs; empaquetan lo que docs-content y docs-assets ya contienen.
Resultado esperado
La imagen del backend desplegada expone los metadatos de docs previstos, sirve el índice de docs empaquetado a través de las APIs de docs pública y autenticada, y solo sirve media empaquetada cuando hay presente un bundle real de assets de docs.