From 5e345c5567dc7a94f887602acca40b2b94bdb01d Mon Sep 17 00:00:00 2001 From: mptyl Date: Sun, 12 Jul 2026 10:07:39 +0200 Subject: [PATCH] docs: clarify host and container secret paths --- docs/installazione-docker-4-contesti.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/installazione-docker-4-contesti.md b/docs/installazione-docker-4-contesti.md index bdf4ace5..a867cc20 100644 --- a/docs/installazione-docker-4-contesti.md +++ b/docs/installazione-docker-4-contesti.md @@ -76,6 +76,14 @@ In `install -m 600 /dev/null DEST`: - `-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 percorso `/etc/thothii` è solo una convenzione dell'esempio per un server Linux: il software +non cerca automaticamente le API key in `/etc`. Il percorso host è quello indicato nelle +variabili `THT_*_SECRET_FILE`; Compose legge quel file e lo monta nel container al percorso +interno dichiarato dal servizio, normalmente `/run/secrets/dwh_api_key`, +`/run/secrets/vector_reader_api_key` o `/run/secrets/model_api_key`. Si può usare, ad esempio, +`/srv/thothii/secrets`, `/opt/company/secrets` o un secret manager che materializzi i file, +senza cambiare il codice: va cambiata solo la variabile `THT_*_SECRET_FILE`. + 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 @@ -94,7 +102,7 @@ Per i secret usati da Docker Desktop è preferibile una directory locale non sin 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` +Impostare gli endpoint e i riferimenti ai secret nel servizio core (preferibilmente tramite un file `.env` gestito dall'operatore, non committato): ```sh @@ -111,6 +119,12 @@ export AUTH_MODE=none export THOTH_PUBLIC_EXPOSURE=false ``` +Queste variabili con suffisso `_SECRET_FILE` sono input di Compose sul server host. Non vanno +confuse con le variabili `_FILE` viste dal processo dentro il container: ad esempio +`THT_MODEL_API_KEY_SECRET_FILE=/etc/thothii/model-api-key` viene trasformata dal file +`deploy/compose.production.yaml` in `THT_MODEL_API_KEY_FILE=/run/secrets/model_api_key`. +Il backend legge quindi `/run/secrets/model_api_key`, non `/etc/thothii/model-api-key`. + 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: