ThothII/tools/tht/README.md

Native installation CLI

Shell configuration

The schema-v2 thothii-installation.yaml accepts this optional section:

shell:
  mode: full
  defaultLocale: en

Omitted shell settings resolve to mode: embedded, defaultLocale: en, and adapter: omics-portal. Supported modes are full and embedded. The default locale accepts well-formed BCP47 language tags, including tags without a UI catalog (for example fr-CA or sr-Latn-RS). Syntax follows RFC 5646, including private use and grandfathered tags; duplicate variants and extension singletons are rejected. The installation preserves the supplied tag; the frontend resolves available translations and falls back to English. No catalog or language-registry allowlist is imposed by the installer. The only supported adapter is omics-portal. Invalid values and unknown descriptor fields are rejected. In full mode, a known adapter setting is ignored and omitted from the resolved public configuration. Shell selection is independent of profile and authentication.

Operational guide: shell configuration and deployment. For Omics server identity, use upstream integration: the CLI's auth configure configures local/OIDC, not an upstream login. A mounted auth.yaml/runtime projection cannot coexist with core AUTH_MODE=upstream.

New installations can select these values with tht setup --shell-mode full --shell-default-locale en. The optional --shell-adapter omics-portal selects the embedded adapter explicitly. Corresponding environment answers are THT_SETUP_SHELL_MODE, THT_SETUP_SHELL_DEFAULT_LOCALE, and THT_SETUP_SHELL_ADAPTER; explicit flags take precedence. Omitting all three preserves the existing setup descriptor format and uses the defaults at load time. Setup does not overwrite an existing descriptor with different settings.

Public runtime projection

The installation generation workflow (modelprojection.Generate, used by setup, lifecycle operations, and installation generate) publishes generated/frontend/config.js next to the model artifacts, relative to the descriptor directory. It contains only:

window.__THOTHII_CONFIG__ = {
  "backendBaseUrl": "/api",
  "shell": {
    "mode": "embedded",
    "defaultLocale": "en",
    "adapter": "omics-portal"
  }
};

For full mode, shell.adapter is absent. No secret values, model configuration, authentication configuration, or host filesystem paths enter this JavaScript. The standalone browser API address remains same-origin /api; it never uses the private nginx upstream http://core:8787. The Omics document must continue to supply its same-origin /datamart-builder/api override when mounting the application under that prefix; selecting an adapter does not infer API routing.

The automatically included generated/compose.models.yaml adds a read-only file bind from generated/frontend/config.js to /usr/share/nginx/html/config.js on the frontend service. Missing sources fail instead of becoming directories (bind.create_host_path: false). The frontend receives THT_FRONTEND_CONFIG_REVISION=sha256:<hash-of-config.js-bytes> so Compose recreates it when public settings change. Shell changes do not revise core's model settings. Only the public file is mounted into the frontend, not the generated directory.

Publication retains the existing whole-generation replacement and rollback behavior. Identical outputs keep file identities; projection drift checks include the public file, Compose definition, and POSIX read permissions. Candidate directories are explicitly set to 0755 and files to 0644, independent of the host umask, so nginx and core can read their file mounts under different UIDs. The enclosing private installation directory is not made public. Existing permission drift is repaired by publishing a new complete generation, using the same rollback path as content changes. A running container requires the normal Compose lifecycle step to pick up a changed file bind. No image rebuild is needed. The generic image retains its empty fallback config, and nginx already serves /config.js with no-store, no-cache, must-revalidate.

docker/smoke/frontend-smoke.sh checks both the generic image fallback and the installed public projection. Its optional file argument permits the same check against generated output in targeted host tests.

To generate files before rebuilding or launching containers, use the upgraded CLI:

/usr/local/bin/tht --installation /Users/mp/projects/ThothII/deploy/psd/thothii-installation.yaml installation generate

This command validates the installation and publishes the common runtime generation. It invokes no Docker commands and does not modify the descriptor, authored model catalog, environment, or authentication configuration. A shell-only descriptor change preserves model projection contents, while the common generation may replace their file identities. It is not a shell-only writer: model projections are always derived from the current descriptor. Run the existing preview rebuild after this command to replace containers with the upgraded images and updated projection mounts.