docs: clarify Docker secrets and workspace configuration
This commit is contained in:
@@ -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/<utente>/.thothii/secrets
|
||||
umask 077
|
||||
read -r -s secret; printf '%s' "$secret" > /mnt/c/Users/<utente>/.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/<workspace>/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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user