Antylogic
DemoApp login

399 operational guides

Docs sections
DocsDocumentation
Device

Prepare the remote documentation bundle

Prepares the content consumed by the Docs routes. With a DOCS ref configured, it downloads the remote repository, syncs articles and assets, and writes articles.json and manifest.json. With no ref configured, it keeps the existing local content and exits successfully.

In this article

This guide is for release operators and build owners who need to get the documentation bundle ready before packaging the backend. The action is not run from the app or from an API: it is an operational shell step.

The result is then consumed by the Docs API, both on /api/public/docs and on /api/app/docs. The Antylogic Docs screen only validates that the runtime reads the already prepared bundle.

Before you start

  • Run from backend or from an equivalent cwd where scripts/sync-docs-content.mjs exists.
  • Have sh, git and node available in the build environment.
  • Guarantee write access to DOCS_CONTENT_OUTPUT, DOCS_ASSETS_OUTPUT and DOCS_CHECKOUT_DIR.
  • Define a ref if remote content should be regenerated: DOCS_REF_DEPLOY_<ENV>, DOCS_REF_DEPLOY, DOCS_VERSION_DEPLOY_<ENV> or DOCS_VERSION.
  • For private repositories, provide DOCS_REPOSITORY_URL or compatible GitLab credentials.

Instructions

  1. 1.

    Confirm the execution environment

    Enter backend and check that the process can run shell, git and node. If no environment is passed to the script, it uses DEPLOY_ENV and then dev.

  2. 2.

    Define the DOCS ref and version

    Decide which content must be embedded. The ref is resolved with priority per environment: DOCS_REF_DEPLOY_<ENV>, DOCS_REF_DEPLOY, DOCS_VERSION_DEPLOY_<ENV> and DOCS_VERSION. The visible version uses DOCS_VERSION_DEPLOY_<ENV>, DOCS_VERSION and finally the ref.

  3. 3.

    Configure repository access

    When there is a ref, the script uses DOCS_REPOSITORY_URL if it is defined. Otherwise it builds a GitLab URL with a compatible token, CI_JOB_TOKEN or the public URL of the docs project.

  4. 4.

    Run the preparation

    Launch scripts/prepare-docs-content.sh [environment]. With a remote ref, the script creates a temporary checkout, runs fetch --depth 1, a detached checkout of FETCH_HEAD and executes sync-docs-content.mjs with the DOCS paths and metadata.

  5. 5.

    Review the generated content

    Check that DOCS_CONTENT_OUTPUT contains articles.json and manifest.json. The manifest must record the version, generation date, source, project, ref, locales, platforms and asset roots.

  6. 6.

    Package into the runtime

    Verify that the backend build copies the already prepared docs-content and docs-assets. The Dockerfiles do not regenerate the bundle; they only set DOCS_CONTENT_PATH, DOCS_ASSETS_PATH and ANTYLOGIC_DOCS_VERSION.

  7. 7.

    Verify the Docs API

    After starting or deploying the runtime, check /api/public/docs without authentication and /api/app/docs with an authenticated session. In the GB demo, Harbor Demo Group can be used to validate the Docs screen, but bundle preparation is global.

  8. 8.

    Handle alternative cases

    If there is no DOCS ref, the correct result is to keep the local content. If the remote checkout works but the sync fails, DOCS_ALLOW_LOCAL_FALLBACK can keep the local articles.json depending on its value.

Validations and limits

  • DOCS_CHECKOUT_DIR cannot be empty, /, . or ..
  • git fetch and git checkout must complete; network or authentication failures abort before the local fallback.
  • The remote source must include a supported path, such as docs-content/articles.json, articles.json or wiki-generated-data.ts.
  • articles.json must be an array or an object with an articles array.
  • If the source is TypeScript, it must contain generatedWikiGuideData with the expected terminator.
  • DOCS_ASSETS_OUTPUT is reset before copying assets when the sync receives it.
  • Without articles.json, the consuming API responds 503 documentación no configurada; if it cannot decode it, it responds 500 documentación no disponible.
  • The asset routes clean the requested path and reject traversal before serving files from DOCS_ASSETS_PATH.
  • /api/version exposes docs.version from ANTYLOGIC_DOCS_VERSION, which may differ from articles.json.version if the build receives another version.

Expected result

The runtime ends up with a Docs bundle that is either prepared or kept locally. The public and authenticated documentation routes can read the same content, serve assets from DOCS_ASSETS_PATH and expose the operational version on /api/version.

Related articles