49 lines
3.3 KiB
Markdown
49 lines
3.3 KiB
Markdown
# 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.
|