# Docker installation in the current operating contexts

Rendering and authentication are independent of these Docker contexts. Explicitly
select full/en for the Mac, full/OIDC for an autonomous server, or
embedded/upstream for Omics. The same frontend image supports both renderings;
generated `config.js` and the host page decide the container, while the backend
and trusted proxy decide identity. See [shell configuration and deploy](operations/shell-and-localization.md)
and [server portal authentication](install/authentication-upstream.md). Do not
apply the standalone server authentication projection to the Omics upstream path.

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 run --workspace <workspace-id>
```

Per rimuovere soltanto gli indici e gli artifact ricostruibili, preservando Memory e domande risolte:

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