Antylogic
DemoApp login

399 operational guides

Docs sections
DocsDocumentation
Device

Resolve the Docs configuration

Validate that Antylogic loaded, at backend start-up, the documentation bundle, the assets root and the Cache-Control policies shared by the public documentation and the authenticated Docs screen.

In this article

Use this guide after a deployment or a bundle change to check that the help served on the landing and in the app comes from the same runtime configuration.

There is no screen to edit DOCS_*: resolution happens during backend start-up and stays fixed until the process restarts. The check is done with the Docs endpoints, the authenticated screen and, where appropriate, a technical review of headers.

Before you start

  • The backend must start and run config.Load() before registering routes.
  • A bundle with articles.json must exist at DOCS_CONTENT_PATH or at the default path ./docs-content.
  • The assets linked by the articles must be under DOCS_ASSETS_PATH or under the default path ../frontend/landingpage/public/product-screenshots/docs.
  • To validate /api/app/docs, use an authenticated session of the GB demo, for example Harbor Demo Group at Harbor Soho.

Instructions

  1. 1.

    Confirm the effective configuration

    Review DOCS_CONTENT_PATH, DOCS_ASSETS_PATH, DOCS_CACHE_CONTROL_DEFAULT and DOCS_CACHE_CONTROL_ASSETS before testing the help. If they are not defined, the backend uses ./docs-content, ../frontend/landingpage/public/product-screenshots/docs, public, max-age=60 and public, max-age=31536000, immutable. Empty or whitespace-only values do not replace the base configuration.

  2. 2.

    Validate the public index

    Open GET /api/public/docs?locale=en&platform=mobile without signing in. The response must show version, article_count and sections; this confirms that DOCS_CONTENT_PATH resolves a readable articles.json for the public documentation.

  3. 3.

    Open the authenticated Docs screen

    With the Harbor Demo User session active, open antylogic://docs. The DocumentationPage screen consumes /api/app/docs, requires authentication through requireAuthMiddleware and must present the same bundle as the public index, with no additional granular Docs permission.

  4. 4.

    Check articles and assets

    From the index, open an article and verify that its media resolves to /api/public/docs/assets/{path} or /api/app/docs/assets/{path}. The backend cleans the path, joins it to DOCS_ASSETS_PATH and only serves files that remain inside that root.

  5. 5.

    Interpret refreshes and caching

    The service reuses articles.json while its ModTime does not advance and reads it again when it detects a more recent modification. If the JSON carries no version, it exposes the UTC ModTime in RFC3339 format. Changing DOCS_* variables requires restarting the backend; changing the file can refresh the content by ModTime.

Validations and limits

  • Only GET and HEAD are valid methods for handleDocs; other methods return 405 metodo no permitido.
  • If DOCS_CONTENT_PATH points to a directory, articles.json is looked up inside it; if it points to a .json file, that file is used directly.
  • If articles.json is missing, GET requests return 503 documentacion no configurada; if the JSON does not decode, they return 500 documentacion no disponible.
  • DOCS_CACHE_CONTROL_DEFAULT applies to index and detail; DOCS_CACHE_CONTROL_ASSETS applies to assets.
  • A non-existent asset or a directory returns 404; an empty path, . or one containing ../ is rejected and does not serve files outside DOCS_ASSETS_PATH.
  • HEAD on a non-asset route responds 200 after validating method and service, without reading articles.json or returning a body.
  • The Dockerfiles set DOCS_CONTENT_PATH and DOCS_ASSETS_PATH to image runtime paths; the cache policies stay at defaults unless a deployment override is applied.
  • The inspected bundle backend/docs-content/articles.json declares version 2026-06-18 and generated_at 2026-06-18T10:44:34.592Z; do not use it as proof of later changes without regenerating the bundle.

Expected result

Public and authenticated documentation are validated against a single shared Docs service: the same articles.json, the same assets root and separate Cache-Control policies for JSON content and media files.

Related articles