Docker installation in the current operating contexts

ThothII uses one Compose topology:

frontend
core
catalog-db
qdrant
embedding
embedding-model-init
catalog-migrate (one-shot)

Qdrant and Ollama embedding are required internal Compose services. Only DWH and the LLM remain external. The fixed model is qwen3-embedding:0.6b with 1024 dimensions and cosine distance; embedding-model-init prepares it before core starts.

flowchart TB
    INSTALL["Installation descriptor"] --> CONTEXT{Context}
    CONTEXT --> LOCAL["Local\nCompose local"]
    CONTEXT --> SERVER["Server\nCompose server"]
    CONTEXT --> SESSION["Session server\noperator services"]
    CONTEXT --> AUTH["Auth runtime\nprojection services"]
    LOCAL --> BUNDLE["Common secret bundle"]
    SERVER --> BUNDLE
    SESSION --> BUNDLE
    AUTH --> BUNDLE
    BUNDLE --> SERVICES["Frontend, core, catalog DB, vector, embedding"]

Short ownership contract

Componente	Ownership	Contratto operativo
DWH	External	External endpoint configured by the installation.
LLM	External	Endpoint or policy outside the internal semantic infrastructure.
Qdrant	Internal	Required internal Compose service with persistent `qdrant-data` volume.
Ollama embedding	Internal	Required internal Compose service for `qwen3-embedding:0.6b`.

Local path: setup, migration, start

The normal local path is Install and first start. It uses tht setup to create the selected installation-local descriptor and runs the catalog migration explicitly before application startup.

If an operator intentionally prepares the descriptor and protected files by hand, the equivalent foreground launch is:

cp deploy/env/local.env.example deploy/env/local.env
cp deploy/secrets/thothii.secrets.example deploy/secrets/thothii.secrets
chmod 600 deploy/secrets/thothii.secrets

# Copy docs/install/examples/thothii-installation.local.yaml to a protected operator path,
# replace every placeholder, chmod it 600, then set that exact path as
# THT_INSTALLATION_CONFIG_SOURCE in deploy/env/local.env.

./scripts/run-stack.sh

Set these values in deploy/env/local.env:

PI_AUTH_FILE
THT_SECRETS_FILE
THT_INSTALLATION_CONFIG_SOURCE (the exact protected host thothii-installation.yaml)
THT_WORKSPACE_GIT_REMOTE
DWH endpoint
LLM endpoint

Do not put secrets in .env. Runtime secrets belong in the deploy/secrets/thothii.secrets bundle.

Secret bundle

The documented and supported bundle keys are:

THT_MODEL_API_KEY=...
THT_DWH_API_KEY=...
OPENAI_API_KEY=...

THT_MODEL_API_KEY is available only as an explicitly declared catalog bundle key. A metadata-generation provider references one audited bundle name from deploy/secrets/README.md through modelCatalog.providers.<provider>.authentication.apiKeyEnv. apiKeyEnv may be omitted only for an explicit endpoint that accepts unauthenticated requests; hosted/default endpoints remain keyed. Provider/model/endpoint settings stay in the protected installation descriptor; raw keys do not.

Compose mounts exactly THT_INSTALLATION_CONFIG_SOURCE into core as a read-only config and sets the backend-only runtime path THT_INSTALLATION_CONFIG_FILE to /run/thothii-installation/thothii-installation.yaml. Do not set the runtime path in the host env. Descriptor and bundle changes are loaded only after application restart.

A private PEM CA remains outside the bundle and must be mounted through a reviewed Compose override.

Preprocessing

Preprocessing runs through the native host CLI and the installation descriptor:

tht --installation /percorso/assoluto/thothii-installation.yaml \
  workspace preprocess evidence --workspace <workspace-id>
tht --installation /percorso/assoluto/thothii-installation.yaml \
  workspace preprocess dwh --workspace <workspace-id>

The CLI runs the profile-gated workspace-maintenance service. See the preprocessing contract and the Evidence guide for details.

Server

For server installations, use the server profile with the session overlay:

docker compose --env-file deploy/env/server.env \
  -f compose.yaml -f deploy/compose.server.yaml \
  -f deploy/compose.session-server.yaml.example up --build -d

Also see Workspace operations. Server deployment, reverse-proxy, backup, and recovery remain manual-gated operations; do not treat the local profile as a server replacement.

4.5 KiB Raw Blame History