Docker installation in the current operating contexts

ThothII uses one Compose topology:

frontend
core
qdrant
embedding
embedding-model-init

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, 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`.

Comando standard locale

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.

docker compose --env-file deploy/env/local.env \
  -f compose.yaml -f deploy/compose.local.yaml up --build -d

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 remains Pi-only. A metadata-generation model instead references one audited bundle name from deploy/secrets/README.md through metadataGeneration.models[].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
tht --installation /percorso/assoluto/thothii-installation.yaml workspace preprocess dwh

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:

docs/install/local-workspace-registry.md
docs/install/server-workspace-registry.md

4.0 KiB Raw Blame History