Antylogic
DemoApp login

399 operational guides

Docs sections
DocsDocumentation
Device

Package Docs Into Backend Images

Package the prepared Antylogic documentation bundle into the REST API and Lambda backend images, then verify that the deployed backend serves the same bundle through the public and authenticated docs APIs. This is a CI and deployment operation, not an in-app workflow.

In this article

Use this guide when release operators need to confirm that the documentation shipped with a backend image is the intended bundle for the GB English runtime.

REST and Lambda images package the same prepared docs-content and docs-assets directories, but they expose them from different runtime paths: /app for REST and /var/task for Lambda.

Before you start

  • Run from the backend build context after backend/docs-content and backend/docs-assets have been prepared.
  • Use an authorised release-orchestrated pipeline or an allowed direct tag pipeline under backend/.gitlab-ci.yml rules.
  • For external docs content, configure the relevant DOCS_REF_DEPLOY_<ENV>, DOCS_REF_DEPLOY, DOCS_VERSION_DEPLOY_<ENV> or DOCS_VERSION variables before the pipeline runs.
  • For REST image publishing, provide GitLab Container Registry access to CI_REGISTRY_IMAGE/restapi. For Lambda publishing, provide the AWS OIDC role, ECR login and push access to antylogic-backend-lambda.
  • Run the API smoke checks against the deployed backend image being validated. Use the Harbor Demo User session for authenticated /api/app/docs checks.

Instructions

  1. 1.

    Prepare the docs bundle

    Start the release pipeline for the target environment. The prepare step runs scripts/prepare-docs-content.sh "$ENV_NAME" and creates docs-content/articles.json, docs-content/manifest.json and docs-assets when an external docs ref is configured. If no docs ref is configured, the build uses the local checked-in bundle already present under backend.

  2. 2.

    Build the REST API image

    Run backend:image:restapi:gitlab or build Dockerfile.restapi from backend. The build compiles the Go server, copies /src/docs-content to /app/docs-content, copies /src/docs-assets to /app/docs-assets and sets DOCS_CONTENT_PATH and DOCS_ASSETS_PATH for the runtime server.

  3. 3.

    Build the Lambda image

    Run backend:image:lambda:ecr:dev, backend:image:lambda:ecr:prod or build Dockerfile.lambda from backend. The build compiles the Lambda bootstrap, copies the prepared docs bundle to /var/task/docs-content and /var/task/docs-assets, and uses ANTYLOGIC_DOCS_VERSION from the DOCS_VERSION build argument.

  4. 4.

    Verify the deployed backend

    After deployment, call GET /api/version to confirm the image-level docs.version. Then call GET /api/app/docs?locale=en&platform=web&theme=light with the Harbor Demo User session and GET /api/public/docs?locale=en&platform=web&theme=light without an app session. Both docs index responses should show article_count, sections and version.

  5. 5.

    Check packaged assets when media is used

    If the deployed bundle references media, request a known file through GET /api/public/docs/assets/{path} or GET /api/app/docs/assets/{path}. Treat this as conditional proof only: the checked-in backend/docs-assets directory currently contains only .gitkeep, so fallback-only builds do not prove production media availability.

Validations and limits

  • backend/docs-content/articles.json exists before docker build starts.
  • backend/docs-assets exists before docker build starts, even when it only contains placeholder files.
  • The REST image uses /app/docs-content and /app/docs-assets; the Lambda image uses /var/task/docs-content and /var/task/docs-assets.
  • ANTYLOGIC_DOCS_VERSION comes from the DOCS_VERSION build argument and is separate from the version stored inside articles.json.
  • GET /api/app/docs and GET /api/public/docs return real docs index payloads, not documentation-not-configured service unavailable responses.
  • Do not use HEAD /api/public/docs or HEAD /api/app/docs as package integrity checks because HEAD can return OK before the bundle is loaded.
  • Docs asset requests must stay inside DOCS_ASSETS_PATH, reject traversal, return 404 for missing files and set content type from the file extension when available.
  • Direct local Docker builds do not run sync-docs-content.mjs; they package whatever docs-content and docs-assets already contain.

Expected result

The deployed backend image exposes the intended docs metadata, serves the packaged docs index through both public and authenticated docs APIs, and only serves packaged media when a real docs asset bundle is present.

Related articles