From 7e829a8414bf2b29268fc2eaee70738a98fe5acf Mon Sep 17 00:00:00 2001 From: mptyl Date: Sun, 12 Jul 2026 10:04:41 +0200 Subject: [PATCH] docs: clarify Docker secrets and workspace configuration --- docs/installazione-docker-4-contesti.md | 109 +++++++++++++++++++++--- 1 file changed, 97 insertions(+), 12 deletions(-) diff --git a/docs/installazione-docker-4-contesti.md b/docs/installazione-docker-4-contesti.md index b14f627f..bdf4ace5 100644 --- a/docs/installazione-docker-4-contesti.md +++ b/docs/installazione-docker-4-contesti.md @@ -26,9 +26,18 @@ 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`. +I secret non devono essere inseriti in `deploy/.env`, nei file workspace o negli URL. +`deploy/.env` serve solo a valori di configurazione non riservati (host, porte, nomi di +database): Compose può mostrarne i valori durante `config`, nei log o nella diagnostica. Un +workspace YAML deve contenere al massimo un riferimento come `password_file`, mai la password +stessa; gli URL non devono contenere user, password o token. + +Salvare invece ogni credenziale in un file separato fuori dal repository. Sul sistema host il +file deve essere leggibile solo dall'utente/servizio che esegue Docker (`0400` se solo lettura, +`0600` se l'operatore deve poterlo aggiornare). Compose lo monta poi nel container come secret +read-only sotto `/run/secrets`. Il `0444` osservabile dentro il container è normale per il +mount dei secret Docker e non rende il file host pubblico: il file host resta protetto e il +container riceve una copia/mount temporaneo non scrivibile. 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) @@ -44,16 +53,47 @@ nomi di servizio della rete Docker. ### Configurazione -Creare i file secret fuori dal repository: +Creare i file secret fuori dal repository. Su Linux/macOS: ```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 +sudo install -d -m 700 /etc/thothii +sudo install -m 600 /dev/null /etc/thothii/dwh-api-key +sudo install -m 600 /dev/null /etc/thothii/vector-reader-api-key +sudo install -m 600 /dev/null /etc/thothii/vector-writer-api-key +sudo install -m 600 /dev/null /etc/thothii/model-api-key +sudo install -m 600 /dev/null /etc/thothii/ca-chain.pem + +# Scrivere il valore senza mostrarlo nella shell history: +sudo sh -c 'umask 077; printf "%s" "$(cat)" > /etc/thothii/dwh-api-key' \ + < /percorso/protetto/dwh-api-key ``` +`install` è un comando Unix per creare/copiare un file impostando contestualmente i permessi. +In `install -m 600 /dev/null DEST`: + +- `/dev/null` è una sorgente vuota, quindi il comando crea (o sostituisce) `DEST` senza + inserire una password; +- `-m 600` imposta i permessi `rw-------` (lettura/scrittura solo per il proprietario); +- `DEST` è il file che l'operatore deve poi riempire con il secret. + +Il comando non è un gestore di password e non va usato per stampare il secret sulla riga di +comando. Su Windows è preferibile usare WSL2 per creare il file con permessi Unix, oppure +creare un file locale ACL-protetto tramite uno strumento aziendale di gestione dei secret. Non +usare `ConvertFrom-SecureString` come contenuto del file: produce una rappresentazione cifrata +che ThothII non può usare come API key. + +```sh +# Dentro WSL2; il path /mnt/c/... deve essere condiviso con Docker Desktop. +mkdir -p /mnt/c/Users//.thothii/secrets +umask 077 +read -r -s secret; printf '%s' "$secret" > /mnt/c/Users//.thothii/secrets/dwh-api-key +unset secret +``` + +Per i secret usati da Docker Desktop è preferibile una directory locale non sincronizzata e +accessibile a Docker Desktop; non usare una cartella Git o OneDrive condivisa. In alternativa, +creare i file dentro WSL2 con `umask 077` e passare a Compose il path Windows risultante. + Impostare gli endpoint e i secret nel servizio core (preferibilmente tramite un file `.env` gestito dall'operatore, non committato): @@ -71,9 +111,54 @@ 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`. +Preparare un file YAML in `deploy/workspaces/`. Il workspace è la configurazione logica di una +installazione: seleziona gli adapter, gli endpoint non riservati e le radici persistenti. Per +esempio, con DWH REST e vector DB HTTP: + +```yaml +language: en +dwh: + type: thoth_rest + database: {database: warehouse, schema: datawarehouse} + endpoint: {base_url: https://dwh.internal.example} +vectors: + type: thoth_vector_http + reader: {base_url: https://vectors.internal.example} + writer: {base_url: https://vectors.internal.example} +roots: {artifacts: artifacts, indexes: indexes, sessions: sessions} +evidence: {source_root: /data/source, evidence_dir: evidence} +embeddings: {base_url: https://embeddings.internal.example, model: nomodel, dim: 768} +``` + +Con DWH PostgreSQL e pgvector raggiungibili direttamente dalla rete Docker: + +```yaml +language: en +dwh: + type: postgres_direct + connection: {host: dwh.internal.example, database: warehouse, schema: public, + user: thoth_reader, password_file: /run/secrets/dwh_password} +vectors: + type: pgvector_direct + reader: {host: vector.internal.example, database: thoth, schema: vectors, + user: thoth_vector_reader, password_file: /run/secrets/vector_reader_password} + writer: {host: vector.internal.example, database: thoth, schema: vectors, + user: thoth_vector_writer, password_file: /run/secrets/vector_writer_password} +roots: {artifacts: artifacts, indexes: indexes, sessions: sessions} +``` + +I nomi dei `type` sono contratti applicativi, non descrizioni libere: usare quelli esposti da +`tht doctor` e dagli esempi del repository (`thoth_rest`, `thoth_vector_http`, +`postgres_direct`, `pgvector_direct`). `dwh.type` sceglie come interrogare il DWH; `vectors.type` +sceglie come leggere/scrivere il vector DB. Cambiare questi valori può richiedere anche campi +specifici dell'adapter e secret file coerenti. + +`roots` contiene percorsi logici, non percorsi host arbitrari. Con `THT_DATA_ROOT=/data`, +`artifacts: artifacts` diventa `/data/workspaces//artifacts` (e analogamente per +`indexes` e `sessions`), evitando che un YAML possa scrivere fuori dal volume applicativo. +Un path host va esposto esplicitamente con un bind mount read-only/read-write nel Compose e poi +referenziato dal workspace secondo le regole di sicurezza; non inserire `/Users/...` o +`C:\\...` direttamente in un workspace destinato a più sistemi operativi. ### Avvio e verifica