docs: add Docker installation guide for four contexts

2026-07-12 09:49:09 +02:00
parent 2302286ea1
commit b07f422bb3
3 changed files with 237 additions and 0 deletions
@@ -8,6 +8,8 @@ La documentazione è divisa in due aree:

 Come funziona il sistema: architettura, specifiche di design delle singole funzionalità, piani di implementazione, report di test. Parte da qui: [Panoramica dell'architettura](architecture/overview.md).

+Per installare l'applicazione in Docker nei diversi contesti operativi: [Installazione Docker nei quattro contesti](installazione-docker-4-contesti.md).
+
 ## Considerazioni Generali

 Note operative e di configurazione che non sono specifiche del dominio ThothII ma riguardano l'ambiente di sviluppo condiviso con altri progetti — ad esempio come Pi (il coding agent) risolve i modelli a livello built-in, utente e progetto. Parte da qui: [Configurazione dei modelli in Pi](general/pi-configuration.md).
@@ -0,0 +1,234 @@
+# Installazione Docker nei quattro contesti operativi
+
+Questa guida descrive l'installazione di ThothII usando le due immagini applicative:
+
+- `thothii-core`: backend Fastify, harness `tht` e Pi;
+- `thothii-frontend`: frontend React servito da nginx.
+
+I database e i servizi di embedding restano esterni, salvo il profilo opzionale
+`local-vector`, che avvia un PostgreSQL/pgvector nello stesso progetto Compose.
+
+## Prerequisiti comuni
+
+Installare Docker Engine/Compose v2 sul server oppure Docker Desktop su macOS/Windows.
+La macchina deve poter raggiungere:
+
+- il DWH/DWH REST, se usato dal workspace;
+- il vector DB REST o pgvector;
+- il servizio di embedding (Ollama o endpoint compatibile);
+- il provider del modello Pi, se si usano provider hosted.
+
+Clonare il repository e lavorare dalla sua radice:
+
+```sh
+git clone <URL-REPOSITORY> ThothII
+cd ThothII
+cp deploy/env.example deploy/.env       # solo per sviluppo locale
+```
+
+I secret non devono essere inseriti in `deploy/.env`, nei file workspace o negli URL. Usare
+file esterni con permessi `0400`/`0600`; per i secret Compose production il montaggio runtime
+accetta il normale `0444` Docker sotto `/run/secrets`.
+
+Il modello Pi usa `THT_MODEL_API_KEY_SECRET_FILE` per i provider autenticati con una singola
+chiave. Provider composti (Bedrock, Azure OpenAI Responses, Cloudflare Workers AI/Gateway)
+sono rifiutati esplicitamente: richiedono un bundle di credenziali non rappresentabile da un
+solo file.
+
+## 1. Server applicativo insieme a DWH e vector DB
+
+Questo profilo è adatto quando ThothII, il database relazionale e il vector DB sono nella
+stessa rete/server, ma i database non devono necessariamente essere containerizzati da
+ThothII. Si usa il profilo `external`; gli endpoint possono essere nomi DNS, IP privati o
+nomi di servizio della rete Docker.
+
+### Configurazione
+
+Creare i file secret fuori dal repository:
+
+```sh
+install -m 600 /dev/null /etc/thothii/dwh-api-key
+install -m 600 /dev/null /etc/thothii/vector-reader-api-key
+install -m 600 /dev/null /etc/thothii/vector-writer-api-key
+install -m 600 /dev/null /etc/thothii/model-api-key
+install -m 600 /dev/null /etc/thothii/ca-chain.pem
+```
+
+Impostare gli endpoint e i secret nel servizio core (preferibilmente tramite un file `.env`
+gestito dall'operatore, non committato):
+
+```sh
+export THT_DB_NAME=warehouse
+export THT_DWH_REST_URL=https://dwh.internal.example
+export THT_VEC_REST_URL=https://vectors.internal.example
+export THT_OLLAMA_URL=https://embeddings.internal.example
+export THT_DWH_API_KEY_SECRET_FILE=/etc/thothii/dwh-api-key
+export THT_VEC_API_KEY_SECRET_FILE=/etc/thothii/vector-reader-api-key
+export THT_VEC_WRITE_API_KEY_SECRET_FILE=/etc/thothii/vector-writer-api-key
+export THT_MODEL_API_KEY_SECRET_FILE=/etc/thothii/model-api-key
+export THT_CA_SECRET_FILE=/etc/thothii/ca-chain.pem
+export AUTH_MODE=none
+export THOTH_PUBLIC_EXPOSURE=false
+```
+
+Preparare il workspace in `deploy/workspaces/` impostando `dwh.type` e `vectors.type` in
+funzione del trasporto disponibile (`thoth_rest`/REST oppure adapter diretto). Le radici
+relative (`roots`) vengono risolte sotto il volume Docker `/data`.
+
+### Avvio e verifica
+
+```sh
+docker compose -f compose.yaml -f deploy/compose.production.yaml \
+  --profile external up --build --wait
+
+docker compose -f compose.yaml -f deploy/compose.production.yaml \
+  --profile external exec core /opt/venv/bin/tht doctor --json
+./scripts/docker-smoke.sh
+```
+
+Il frontend è pubblicato su `127.0.0.1:8080` per default. Per esposizione pubblica usare un
+reverse proxy autenticato TLS; non impostare `THOTH_PUBLIC_EXPOSURE=true` senza `AUTH_MODE=upstream`
+e senza il proxy che inietta `X-Authenticated-User`.
+
+## 2. Mac locale con DWH esterno e vector DB locale
+
+Questo è il profilo consigliato per un Mac Apple Silicon o Intel: Docker Desktop ospita
+pgvector e ThothII, mentre DWH ed embeddings possono essere remoti. Ollama eseguito sul Mac è
+raggiungibile dai container con `host.docker.internal`.
+
+Creare quattro password locali, fuori Git:
+
+```sh
+mkdir -p ~/.thothii/secrets
+for name in bootstrap migrator reader writer; do
+  umask 077; openssl rand -base64 32 >"$HOME/.thothii/secrets/$name"
+done
+export THT_VECTOR_BOOTSTRAP_PASSWORD_SECRET_FILE="$HOME/.thothii/secrets/bootstrap"
+export THT_VECTOR_MIGRATOR_PASSWORD_SECRET_FILE="$HOME/.thothii/secrets/migrator"
+export THT_VECTOR_READER_PASSWORD_SECRET_FILE="$HOME/.thothii/secrets/reader"
+export THT_VECTOR_WRITER_PASSWORD_SECRET_FILE="$HOME/.thothii/secrets/writer"
+export THT_OLLAMA_URL=http://host.docker.internal:11434
+```
+
+Avviare il profilo:
+
+```sh
+docker compose -f compose.yaml -f deploy/compose.local-vector.yaml \
+  --profile local-vector up --build --wait
+```
+
+Per eseguire i job di preprocessing usare anche l'overlay che abilita la catena
+health-check → reconcile → migrate:
+
+```sh
+docker compose -f compose.yaml -f deploy/compose.local-vector.yaml \
+  -f deploy/compose.preprocess.yaml -f deploy/compose.preprocess-local-vector.yaml \
+  --profile local-vector --profile preprocess build preprocess-evidence
+docker compose -f compose.yaml -f deploy/compose.local-vector.yaml \
+  -f deploy/compose.preprocess.yaml -f deploy/compose.preprocess-local-vector.yaml \
+  --profile local-vector --profile preprocess run --rm preprocess-evidence
+```
+
+Montare i testi Evidence in `/data/source/evidence` tramite il workspace o un override Compose.
+Il volume `thoth_data` contiene sessioni, artefatti e corpus; `vector_data` contiene solo
+pgvector. Per verificare rotazione credenziali e recovery:
+
+```sh
+./scripts/local-vector-smoke.sh
+./scripts/local-vector-smoke.sh --backup-restore
+```
+
+## 3. PC Windows locale
+
+Usare Docker Desktop con backend WSL2, abilitare l'integrazione con la distribuzione WSL e
+conservare il repository in un percorso condiviso con Docker. È preferibile lavorare da
+PowerShell nella directory del progetto.
+
+```powershell
+New-Item -ItemType Directory -Force "$HOME\.thothii\secrets" | Out-Null
+foreach ($name in @("bootstrap", "migrator", "reader", "writer")) {
+  $bytes = New-Object byte[] 32
+  [Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
+  [Convert]::ToBase64String($bytes) | Set-Content -NoNewline "$HOME\.thothii\secrets\$name"
+}
+$env:THT_VECTOR_BOOTSTRAP_PASSWORD_SECRET_FILE = "$HOME\.thothii\secrets\bootstrap"
+$env:THT_VECTOR_MIGRATOR_PASSWORD_SECRET_FILE = "$HOME\.thothii\secrets\migrator"
+$env:THT_VECTOR_READER_PASSWORD_SECRET_FILE = "$HOME\.thothii\secrets\reader"
+$env:THT_VECTOR_WRITER_PASSWORD_SECRET_FILE = "$HOME\.thothii\secrets\writer"
+$env:THT_OLLAMA_URL = "http://host.docker.internal:11434"
+```
+
+Da PowerShell, i path assoluti vengono passati a Compose tramite le variabili precedenti; non
+scrivere password direttamente nello YAML. Avviare lo stesso profilo del Mac:
+
+```powershell
+docker compose -f compose.yaml -f deploy/compose.local-vector.yaml `
+  --profile local-vector up --build --wait
+docker compose -f compose.yaml -f deploy/compose.local-vector.yaml `
+  -f deploy/compose.preprocess.yaml -f deploy/compose.preprocess-local-vector.yaml `
+  --profile local-vector --profile preprocess run --rm preprocess-evidence
+```
+
+Se Docker Desktop segnala un bind mount non condiviso, aggiungere la directory del repository
+in Docker Desktop → Settings → Resources → File Sharing. Se Ollama gira su Windows, usare
+`host.docker.internal`; se gira in WSL2, usare l'endpoint raggiungibile dalla rete Docker.
+Verificare il profilo con:
+
+```powershell
+docker compose -f compose.yaml -f deploy/compose.local-vector.yaml --profile local-vector config
+docker compose -f compose.yaml -f deploy/compose.local-vector.yaml --profile local-vector ps
+```
+
+## 4. Server applicativo distinto da DB e Evidence
+
+Questo profilo separa il server Docker di ThothII dal DWH, vector DB e repository Evidence.
+Usare `compose.production.yaml` e configurare gli adapter con endpoint raggiungibili dal
+server applicativo. Le Evidence non devono essere copiate nel container se sono già accessibili
+via HTTP/S3 o tramite un filesystem montato dal sistema operativo.
+
+Configurare firewall e DNS in modo che il server applicativo possa raggiungere solo gli endpoint
+necessari. Esempi di sorgente Evidence:
+
+- `filesystem`: NFS/SMB montato sul server e passato come root read-only al workspace;
+- `http`: URL HTTPS con allowlist/limiti SSRF e cache condizionata;
+- `s3`: bucket/prefix con secret references e endpoint custom solo con trust boundary esplicito.
+
+Impostare `THT_DOCS_ROOT`/il workspace per il path montato oppure configurare il tipo HTTP/S3,
+poi avviare:
+
+```sh
+docker compose -f compose.yaml -f deploy/compose.production.yaml \
+  --profile external config --quiet
+docker compose -f compose.yaml -f deploy/compose.production.yaml \
+  --profile external up --build --wait
+docker compose -f compose.yaml -f deploy/compose.production.yaml \
+  --profile external exec core /opt/venv/bin/tht doctor --json
+```
+
+Per un vector DB remoto usare le chiavi reader/writer distinte quando il servizio lo consente;
+per un DWH REST usare `THT_DWH_REST_URL` e il relativo secret, senza introdurre connessioni
+dirette nel container. Il preprocessing DWH/Evidence può essere eseguito sullo stesso server
+applicativo con un volume `/data` persistente, mantenendo separati i lock e gli artefatti dei
+job.
+
+## Controlli comuni post-installazione
+
+1. `docker compose ... config --quiet` non deve mostrare password o token in chiaro.
+2. `docker compose ... ps` deve mostrare `core` e `frontend` healthy.
+3. `tht doctor --json` deve restituire JSON valido; errori di dipendenza devono restare
+   diagnostici e non esporre secret.
+4. Eseguire lo smoke coerente col profilo (`docker-smoke.sh`, `preprocess-smoke.sh` o
+   `local-vector-smoke.sh`).
+5. Conservare il volume `thoth_data` e i backup pgvector fuori dal ciclo di deploy; usare
+   `down --volumes` solo per ambienti effimeri o dopo aver verificato il backup.
+
+## Risoluzione rapida dei problemi
+
+- **Core healthy ma nessun modello:** controllare `THT_MODEL_API_KEY_SECRET_FILE`, il provider
+  selezionato e che non sia uno dei provider composti non supportati.
+- **Preprocess fallisce subito:** verificare l'overlay `compose.preprocess-local-vector.yaml`,
+  i quattro secret pgvector e che il mount Evidence sia leggibile.
+- **Vector health non disponibile:** controllare `vector-db`, `vector-reconcile`, `vector-migrate`
+  e le password reader/writer; non usare la password bootstrap nelle query applicative.
+- **Evidence non trovate:** controllare il path nel workspace, la rete HTTP/S3 e i limiti di
+  dimensione/paginazione; verificare che il corpus ACTIVE appartenga allo stesso workspace.
@@ -47,6 +47,7 @@ nav:
 - Home: index.md
 - ThothII (Documentazione Tecnica):
  - Panoramica Architettura: architecture/overview.md
+  - Installazione Docker (4 contesti): installazione-docker-4-contesti.md
  - Specifiche di Design:
    - Architettura ThothII: superpowers/specs/2026-06-25-thothii-architecture-design.md
    - Backend: superpowers/specs/2026-06-27-backend-design.md