Antylogic
DemoApp login

399 operational guides

Docs sections
DocsDocumentation
Device

Configure Docs Runtime Paths

Configure the backend runtime so Antylogic reads the docs bundle from `DOCS_CONTENT_PATH`, serves referenced media from `DOCS_ASSETS_PATH`, and applies separate cache headers to docs JSON and media assets.

In this article

Use this guide when an operator or documentation owner needs to point Antylogic Docs at the correct runtime bundle. This is a backend startup configuration task, not an in-app setting.

The same docs service serves the public landing Docs API and the authenticated app Docs screen. Public docs are intentionally readable without app authentication; app docs still require a signed-in app request.

Before you start

  • Deployment or runtime environment access for the backend process.
  • `DOCS_CONTENT_PATH` points to an `articles.json` file or to a directory containing `articles.json`.
  • `DOCS_ASSETS_PATH` points to the root that contains the media paths referenced by article entries.
  • The backend process is started or restarted after the `DOCS_*` values are set.
  • For authenticated verification, use the GB demo session for Harbor Demo Group and Harbor Soho.

Instructions

  1. 1.

    Prepare the docs bundle

    Place the generated docs content and media where the backend can read them. Local defaults are `./docs-content` for content and `../frontend/landingpage/public/product-screenshots/docs` for assets; packaged REST API and Lambda images include bundled docs directories unless equivalent runtime mounts are supplied.

  2. 2.

    Set runtime values before startup

    Set `DOCS_CONTENT_PATH`, `DOCS_ASSETS_PATH`, `DOCS_CACHE_CONTROL_DEFAULT`, and `DOCS_CACHE_CONTROL_ASSETS` in the backend runtime environment. Leave a value unset only when the implemented default is acceptable.

  3. 3.

    Restart the backend

    Start or restart the backend after setting the environment. Route registration creates one docs content service and mounts it under both `/api/public/docs` and `/api/app/docs`; only the generated asset URL prefix changes.

  4. 4.

    Verify public docs

    Call `/api/public/docs` and an English article route without app authentication. For the GB capture plan, use `/api/public/docs/attendance/en-attendance-view-board?locale=en&platform=mobile&theme=light` and confirm the Clock in/out Board article is returned.

  5. 5.

    Verify authenticated app docs

    With Harbor Demo User signed in, open `antylogic://docs/attendance/en-attendance-view-board`. The native Docs screen should load the same configured bundle through `/api/app/docs`.

  6. 6.

    Check media asset resolution

    Open an article that contains media and confirm each `src` is rewritten to the active API prefix. Public articles use `/api/public/docs/assets/{path}`; authenticated app articles use `/api/app/docs/assets/{path}`.

  7. 7.

    Handle common failures

    Use status codes to separate setup problems from lookup problems: missing content returns `503`, invalid JSON returns `500`, unsupported methods return `405`, missing articles return `404`, and missing media returns `404` from the asset route.

Validations and limits

  • Blank or whitespace-only route config overrides are ignored before defaults are selected.
  • A content path ending in `.json` is used directly; every other content path is treated as a directory containing `articles.json`.
  • Unset cache-control values fall back to `public, max-age=60` for JSON and `public, max-age=31536000, immutable` for assets.
  • Docs JSON responses use `DOCS_CACHE_CONTROL_DEFAULT` when the resolved value is non-empty.
  • Docs asset responses use `DOCS_CACHE_CONTROL_ASSETS` when the resolved value is non-empty.
  • Asset paths are cleaned, cannot traverse outside `DOCS_ASSETS_PATH`, must exist, and must not be directories.
  • A successful non-asset `HEAD` response does not prove that the bundle or article exists, because it does not load the content file.

Expected result

After setup, the public Docs API and authenticated app Docs screen read the same configured docs bundle, media resolves through the active docs asset route, and JSON and assets receive their configured cache policies.

Related articles