ThothII/docs/installazione-docker-4-contesti.md

Installazione Docker nei quattro contesti operativi

ThothII viene distribuito con due immagini applicative:

• thothii-core: backend Fastify, harness tht e Pi;
• thothii-frontend: frontend React servito da nginx.

PostgreSQL/pgvector, DWH ed Evidence restano esterni nel profilo predefinito. Il profilo opzionale local-vector avvia PostgreSQL/pgvector nel progetto Compose.

Installazione comune (il comando standard)

Servono Docker Engine/Compose v2 su Linux oppure Docker Desktop su macOS/Windows. Dalla directory in cui si vuole conservare il clone:

git clone <URL-REPOSITORY> ThothII
cd ThothII
cp .env.example .env
mkdir -p deploy/secrets deploy/workspaces
cp deploy/secrets/thothii.secrets.example deploy/secrets/thothii.secrets
chmod 600 deploy/secrets/thothii.secrets

Modificare solo questi file interni al clone:

File	Cosa contiene
.env	endpoint, database, provider, COMPOSE_FILE e COMPOSE_PROFILES; mai password/token
deploy/secrets/thothii.secrets	un bundle NOME=VALORE, mode host 0600 o 0400
deploy/workspaces/<nome>.yaml	adapter, endpoint non riservati, roots ed Evidence

Il file .env viene caricato automaticamente da Docker Compose perché è nella radice del progetto. Il valore predefinito è COMPOSE_FILE=compose.yaml, con profili vuoti e THT_SECRETS_FILE=deploy/secrets/thothii.secrets. Perciò, dopo aver compilato .env, il bundle e almeno il workspace, l'avvio normale è sempre:

docker compose up --build -d

Non occorre usare --env-file, -f o --profile per questa installazione. Verificare lo stato con docker compose ps e aprire http://127.0.0.1:8080. docker compose down conserva il volume thoth_data; usare down --volumes solo per un ambiente effimero.

Formato del bundle unico

deploy/secrets/thothii.secrets è un file di testo locale, non uno script shell. Sono ammessi commenti e righe vuote; ogni altra riga deve essere una sola assegnazione senza spazi:

THT_MODEL_API_KEY=...
THT_DWH_API_KEY=...
THT_VEC_API_KEY=...
THT_VEC_WRITE_API_KEY=...
THT_VECTOR_BOOTSTRAP_PASSWORD=...
THT_VECTOR_MIGRATOR_PASSWORD=...
THT_VECTOR_READER_PASSWORD=...
THT_VECTOR_WRITER_PASSWORD=...

Inserire solo le chiavi necessarie al profilo scelto. Il bundle viene montato in sola lettura nel container come /run/secrets/thothii.secrets; il parser rifiuta duplicati, chiavi sconosciute, valori vuoti, symlink e permessi host troppo aperti. Non inserire secret in .env, nei workspace, negli URL o nell'output di docker compose config.

Una catena CA PEM non può essere inserita nel bundle: contiene whitespace e viene rifiutata dal parser. Se un endpoint usa una CA privata, conservarla nel secret manager/host e aggiungere un override Compose revisionato che monti il file in /run/secrets/ca-chain.pem e imposti THT_SSL_CA (o il parametro dell'adapter). Il clone base non crea quel mount: questa è una limitazione intenzionale da considerare in fase di deployment.

Overlay opzionali tramite .env

Gli overlay non cambiano il comando operativo. Impostare in .env:

# DWH/vector/embedding remoti (server applicativo o server con i DB):
COMPOSE_FILE=compose.yaml:deploy/compose.production.yaml
COMPOSE_PROFILES=

# pgvector locale (Mac, Windows o server autonomo):
COMPOSE_FILE=compose.yaml:deploy/compose.local-vector.yaml
COMPOSE_PROFILES=local-vector

Su Windows usare ; come separatore di COMPOSE_FILE. Per il preprocessing locale aggiungere deploy/compose.preprocess.yaml:deploy/compose.preprocess-local-vector.yaml e impostare COMPOSE_PROFILES=local-vector,preprocess; poi usare docker compose run --rm preprocess-evidence oppure docker compose run --rm preprocess-dwh.

Workspace, adapter e Evidence

Il workspace YAML seleziona il trasporto disponibile. Esempio DWH REST e vector DB HTTP:

language: en
dwh:
  type: thoth_rest
  database: {database: warehouse, schema: datawarehouse}
  endpoint: {base_url: https://dwh.example.test}
vectors:
  type: thoth_vector_http
  reader: {base_url: https://vectors.example.test}
  writer: {base_url: https://vectors.example.test}
roots: {artifacts: artifacts, indexes: indexes, sessions: sessions}
evidence: {source_root: /data/source, evidence_dir: evidence}
embeddings: {base_url: https://embeddings.example.test, model: nomodel, dim: 768}

Esempio con accesso diretto a PostgreSQL e pgvector:

language: en
dwh:
  type: postgres_direct
  connection: {host: dwh.internal, database: warehouse, schema: public,
               user: thoth_reader, password_file: /run/secrets/dwh_password}
vectors:
  type: pgvector_direct
  reader: {host: vector.internal, database: thoth, schema: vectors,
           user: thoth_vector_reader, password_file: /run/secrets/vector_reader_password}
  writer: {host: vector.internal, database: thoth, schema: vectors,
           user: thoth_vector_writer, password_file: /run/secrets/vector_writer_password}
roots: {artifacts: artifacts, indexes: indexes, sessions: sessions}

Questo esempio mostra il contratto dell'adapter: i file indicati da password_file devono essere montati da un override Compose approvato. Il profilo base monta soltanto il bundle unico; per un DWH diretto occorre quindi materializzare il file password dal secret manager e aggiungere il bind mount/runtime adapter corrispondente. Non inserire la password nel workspace o nell'URL.

roots sono relativi e vengono risolti sotto /data/workspaces/<workspace> nel volume Docker; non inserire path host come /Users/... o C:\\.... Per Evidence usare una radice filesystem montata in sola lettura oppure l'adapter HTTP/S3 previsto dal workspace. Per HTTP/S3 definire allowlist, limiti di dimensione/paginazione e una politica egress; non mettere token nelle URI.

1. Server remoto insieme ai database e al vector DB

Usare quando il server Docker è nella stessa rete del DWH e del vector DB (containerizzati o meno). Il file .env può restare sul default, senza profili, impostando gli endpoint raggiungibili localmente:

COMPOSE_FILE=compose.yaml
COMPOSE_PROFILES=
THT_DB_NAME=warehouse
THT_DWH_REST_URL=https://dwh.internal.example
THT_VEC_REST_URL=https://vectors.internal.example
THT_OLLAMA_URL=https://embeddings.internal.example
AUTH_MODE=none
THOTH_PUBLIC_EXPOSURE=false

Riempire nel bundle le chiavi DWH/vector/model necessarie e avviare:

docker compose up --build -d
docker compose exec core /opt/venv/bin/tht doctor --json

Se si abilita l'overlay production, il proxy autenticato TLS deve essere l'unico listener pubblico e deve iniettare X-Authenticated-User; non esporre direttamente la porta pubblicata da nginx.

Se il server deve essere raggiungibile da altri host, sostituire COMPOSE_FILE con compose.yaml:deploy/compose.production.yaml, configurare il proxy autenticato e impostare AUTH_MODE=upstream/THOTH_PUBLIC_EXPOSURE=true come descritto nella sezione di trust boundary.

2. Mac locale

Installare Docker Desktop e, se usato, Ollama sul Mac. Nel .env selezionare il profilo locale:

COMPOSE_FILE=compose.yaml:deploy/compose.local-vector.yaml
COMPOSE_PROFILES=local-vector
THT_OLLAMA_URL=http://host.docker.internal:11434

Nel bundle aggiungere quattro password generate localmente:

THT_VECTOR_BOOTSTRAP_PASSWORD=<valore casuale>
THT_VECTOR_MIGRATOR_PASSWORD=<valore casuale>
THT_VECTOR_READER_PASSWORD=<valore casuale>
THT_VECTOR_WRITER_PASSWORD=<valore casuale>

Poi eseguire il comando standard docker compose up --build -d. Il primo avvio esegue reconciliation dei ruoli e migrazione pgvector. Per preprocessing, impostare il preset indicato sopra e usare docker compose run --rm preprocess-evidence/preprocess-dwh.

3. PC Windows locale

Usare Docker Desktop con backend WSL2 e abilitare la condivisione della directory del clone. Modificare .env con il separatore Windows:

COMPOSE_FILE=compose.yaml;deploy/compose.local-vector.yaml
COMPOSE_PROFILES=local-vector
THT_OLLAMA_URL=http://host.docker.internal:11434

Creare deploy/secrets/thothii.secrets con un editor locale protetto (ACL leggibile solo dall'utente Docker) e le stesse quattro chiavi pgvector del profilo Mac. Non usare ConvertFrom-SecureString: il bundle deve contenere il valore in chiaro per il servizio, con accesso limitato al file. Da PowerShell, dalla radice del clone, eseguire:

docker compose up --build -d
docker compose ps

Se un bind mount viene rifiutato, aggiungere la cartella del repository a Docker Desktop → Settings → Resources → File Sharing. Per Ollama eseguito in WSL2 usare l'indirizzo raggiungibile dalla rete Docker invece di assumere localhost.

4. Server applicativo distinto da DB ed Evidence

Usare il profilo production e consentire dal firewall solo le destinazioni necessarie:

COMPOSE_FILE=compose.yaml:deploy/compose.production.yaml
COMPOSE_PROFILES=
THT_DWH_REST_URL=https://dwh.example.test
THT_VEC_REST_URL=https://vectors.example.test
THT_OLLAMA_URL=https://embeddings.example.test

Il DWH e il vector DB possono essere REST/HTTP oppure adapter diretti (postgres_direct, pgvector_direct) se il server ha connettività TCP. Le Evidence possono essere:

• filesystem NFS/SMB montato sul server e presentato come root read-only;
• endpoint HTTPS, con allowlist e limiti SSRF;
• bucket S3 con secret references e endpoint custom esplicitamente autorizzati.

Il preprocessing può girare sul server applicativo usando il volume /data; mantenere separati workspace, lock e artefatti dei job. Avviare con il comando standard e verificare tht doctor.

Migrazione da installazioni con secret separati

Le variabili THT_*_SECRET_FILE e i file dwh-api-key, vector-reader-api-key, vector-writer-api-key, model-api-key e vector_*_password appartengono al layout precedente. Non vengono importati automaticamente dal bundle. Per migrare:

1. creare deploy/secrets/thothii.secrets mode 0600;
2. copiare ogni valore nel nome chiave corrispondente (THT_DWH_API_KEY, THT_VEC_API_KEY, THT_VEC_WRITE_API_KEY, THT_MODEL_API_KEY o THT_VECTOR_*_PASSWORD), senza virgolette né newline;
3. rimuovere dal .env le variabili _SECRET_FILE e impostare THT_SECRETS_FILE al percorso del bundle (il default relativo è già corretto);
4. eseguire docker compose config --quiet e poi docker compose up --build -d;
5. solo dopo la verifica, cancellare i vecchi file separati.

Una CA PEM resta un'eccezione esterna come descritto sopra. Provider Pi con credenziali composte (Bedrock, Azure OpenAI Responses, Cloudflare Workers AI/Gateway) restano rifiutati finché non viene implementato un adapter dedicato.

Controlli post-installazione

docker compose config --quiet
docker compose ps
docker compose exec core /opt/venv/bin/tht doctor --json
./scripts/docker-smoke.sh

Per il profilo locale usare anche ./scripts/local-vector-smoke.sh; per il preprocessing ./scripts/preprocess-smoke.sh. Non pubblicare .env o deploy/secrets/thothii.secrets nei log, nei backup Git o nei ticket.