# Compose reference for maintainers

This is an internal topology reference, not a second fresh-installation recipe. Operators
start with the [Italian](../install/standalone-manual-it.md) or
[English](../install/standalone-manual-en.md) 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](../contracts/workspace-preprocessing-cli.md).

## 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](../general/pi-configuration.md).
- 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](server-codex-handoff.md) and
[legacy upgrade runbook](server-upgrade-gitea-workspace-v2.md) 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.