Antylogic
DemoApp login

399 operational guides

Docs sections
DocsDocumentation
Device

Prepare Docs Bundle For Deployment

Prepare the documentation bundle that is packaged into a backend REST API or Lambda image, then verify that the deployed runtime can read it through the Docs API.

In this article

Use this guide when a release operator needs to package the latest supported Docs content into a backend image before deployment.

The preparation step is a build-time operation. It resolves a docs ref, optionally checks out an external docs repository, converts the supported source into `docs-content` and `docs-assets`, and leaves local content in place only under the implemented fallback rules.

The clearest runtime proof is the Docs API response: `GET /api/public/docs?locale=en-GB&platform=web` should return bundle metadata, sections, and a resolved locale of `en`.

Before you start

  • Run the preparation from the backend build working directory, where `scripts/prepare-docs-content.sh`, `scripts/sync-docs-content.mjs`, `docs-content`, and `docs-assets` are relative to the Docker build context.
  • When a docs ref is configured, confirm that `git` and `node` are available in the build job.
  • Choose the docs source before building: use `DOCS_REF_DEPLOY_<ENV>`, `DOCS_REF_DEPLOY`, `DOCS_VERSION_DEPLOY_<ENV>`, `DOCS_VERSION`, or an existing local `docs-content/articles.json` only where fallback rules allow it.
  • For private docs repositories, provide `DOCS_REPOSITORY_URL` or GitLab credentials through the supported token variables.
  • Confirm that `DOCS_CHECKOUT_DIR`, `DOCS_CONTENT_OUTPUT`, and `DOCS_ASSETS_OUTPUT` are writable and safe for the build job to recreate.

Instructions

  1. 1.

    Select the deployment environment and docs ref

    Set `DEPLOY_ENV` for the image build. The prepare script uppercases the environment and resolves the docs ref from `DOCS_REF_DEPLOY_<ENV>`, `DOCS_REF_DEPLOY`, `DOCS_VERSION_DEPLOY_<ENV>`, then `DOCS_VERSION`.

  2. 2.

    Confirm repository access

    Use `DOCS_REPOSITORY_URL` when the exact source repository must be controlled. Otherwise the script builds a GitLab URL from `DOCS_PROJECT_DEPLOY` and available token variables, falling back to an unauthenticated public GitLab URL.

  3. 3.

    Run preparation before the image build

    Let the backend image job run `scripts/prepare-docs-content.sh "$ENV_NAME"` before `docker build`. With a docs ref, the script recreates `DOCS_CHECKOUT_DIR`, checks out the selected ref, and delegates conversion to `node scripts/sync-docs-content.mjs`.

  4. 4.

    Review generated outputs

    Check `DOCS_CONTENT_OUTPUT/articles.json` and `DOCS_CONTENT_OUTPUT/manifest.json`. The generated bundle records version, source metadata, derived locales, platforms `mobile`, `tablet`, and `web`, articles, and asset root metadata.

  5. 5.

    Handle fallback deliberately

    If conversion fails after checkout, use `DOCS_ALLOW_LOCAL_FALLBACK` only when shipping the existing local bundle is acceptable. The default `auto` fallback applies only to refs `master` and `main`; pinned refs require an explicit truthy fallback value.

  6. 6.

    Package the backend image

    Build the REST API or Lambda image only after preparation has completed or intentionally fallen back. The Dockerfiles copy `docs-content` and `docs-assets` into the runtime image and set the docs content and asset paths.

  7. 7.

    Verify the deployed Docs API

    Open `GET /api/public/docs?locale=en-GB&platform=web` first. Use Harbor Demo User only for the authenticated check at `GET /api/app/docs?locale=en-GB&platform=web`; both routes read the same prepared bundle.

Validations and limits

  • If no docs ref is configured, the script should exit successfully and leave local `docs-content` in place without regenerating the bundle.
  • `DOCS_CHECKOUT_DIR` must not be empty, `/`, `.`, or `..` before the script deletes and recreates it.
  • The converter must find one supported source file and produce a top-level articles array.
  • `manifest.json` should point to `articles.json` and include `asset_roots.runtime_env` as `DOCS_ASSETS_PATH`.
  • For `locale=en-GB&platform=web`, the runtime response should report locale `en`, platform `web`, `article_count`, and `sections`.
  • A fallback build proves only that existing local content was used; it does not prove that the selected external docs ref converted successfully.

Expected result

The backend image contains the prepared `docs-content` and `docs-assets` bundle, and the deployed runtime can serve it through the public and authenticated Docs API routes.

Related articles