125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# 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.
|
|
|
|
```mermaid
|
|
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](install/first-start.md). 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```dotenv
|
|
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:
|
|
|
|
```sh
|
|
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](contracts/workspace-preprocessing-cli.md) and the
|
|
[Evidence guide](evidence.md) for details.
|
|
|
|
## Server
|
|
|
|
For server installations, use the server profile with the session overlay:
|
|
|
|
```sh
|
|
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](operations/workspaces.md). Server deployment, reverse-proxy,
|
|
backup, and recovery remain manual-gated operations; do not treat the local profile as a server
|
|
replacement.
|