# 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.

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

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

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_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=...
```

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
tht --installation /percorso/assoluto/thothii-installation.yaml workspace preprocess dwh
```

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:

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