ThothII/docs/operations/compose-reference.md

Compose reference for maintainers

This is an internal topology reference, not a second fresh-installation recipe. Operators start with the Italian or English manual. It replaces the duplicated four-context Docker guide without changing the runtime.

The base topology contains frontend, core, catalog-db, qdrant, embedding, embedding-model-init, catalog-migrate and profile-gated workspace-maintenance. Pi runs in core; DWH and generative model endpoints remain installation settings. Reference preprocessing and Memory have distinct lifecycles and collections. See preprocessing.

Configuration and migration boundaries

• Use one physical absolute installation descriptor path, its generated operator environment, Compose project name, base/profile overlays, transport overlays and generated model overlay. Mixing a generic deploy/env/local.env invocation with a native tht installation creates a different stack; it is not an equivalent lifecycle command.
• THT_INSTALLATION_CONFIG_SOURCE identifies the protected host descriptor. The read-only backend runtime mount is /run/thothii-installation/thothii-installation.yaml, exposed through THT_INSTALLATION_CONFIG_FILE; the runtime path is not a host source path.
• Catalog runtime/migrator passwords and provider credentials are protected files. A provider's authentication.apiKeyEnv names an allowed bundle entry; it is not a raw key. Private CAs are separately mounted PEM files, not bundle values. See the repository's deploy/secrets/README.md and the model catalog guide.
• Generate projections after descriptor edits. Do not edit generated model/auth/frontend files. Apply the installation's normal restart process when authored configuration changes.
• Explicitly start catalog-db and run catalog-migrate before application rollout on a fresh database or after an approved schema update. That service runs Catalog and Memory migrations; neither normal backend startup nor tht start implicitly performs them.
• Server deployments retain their reviewed session/auth/network/storage overlays. A writable server Pi-state parent must be initialized with the regular targets expected by the read-only nested mounts; use scripts/prepare-server-pi-state.sh with the installation's verified UID/GID.

Deployment-specific authority

For the prepared generic server environment, the base/profile/session override combination is -f compose.yaml -f deploy/compose.server.yaml -f deploy/compose.session-server.yaml.example, with --env-file supplied before the overrides. Add the reviewed transport/generated overlays for that installation; this fragment alone is not a complete startup command.

The current server handoff and legacy upgrade runbook retain maintenance, backup and rollback gates. Embedded/upstream identity is not standalone OIDC. Local/standalone setup does not authorize replacing a running server stack, resetting volumes, or copying another machine's descriptor. scripts/run-stack.sh remains a low-level path for an explicitly prepared generic environment, not the public manual's default startup command.