docs: define secret paths before file creation

docs/installazione-docker-4-contesti.md

@@ -53,21 +53,41 @@ nomi di servizio della rete Docker.
 
 ### Configurazione
 
-Creare i file secret fuori dal repository. Su Linux/macOS:
+Creare i file secret fuori dal repository. Prima si definiscono i percorsi host nelle variabili
+`THT_*_SECRET_FILE`:
 
 ```sh
-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
+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
 ```
 
+Nella forma documentale, i cinque target sono indicati come
+`<THT_DWH_API_KEY_SECRET_FILE>`, `<THT_VEC_API_KEY_SECRET_FILE>`,
+`<THT_VEC_WRITE_API_KEY_SECRET_FILE>`, `<THT_MODEL_API_KEY_SECRET_FILE>` e
+`<THT_CA_SECRET_FILE>`. Le parentesi angolari sono segnaposto e **non** vanno digitate nella
+shell: nei comandi eseguibili si usano le variabili tra virgolette doppie:
+
+```sh
+for secret_file in \
+  "$THT_DWH_API_KEY_SECRET_FILE" "$THT_VEC_API_KEY_SECRET_FILE" \
+  "$THT_VEC_WRITE_API_KEY_SECRET_FILE" "$THT_MODEL_API_KEY_SECRET_FILE" "$THT_CA_SECRET_FILE"; do
+  sudo install -d -m 700 "$(dirname "$secret_file")"
+done
+sudo install -m 600 /dev/null "$THT_DWH_API_KEY_SECRET_FILE"
+sudo install -m 600 /dev/null "$THT_VEC_API_KEY_SECRET_FILE"
+sudo install -m 600 /dev/null "$THT_VEC_WRITE_API_KEY_SECRET_FILE"
+sudo install -m 600 /dev/null "$THT_MODEL_API_KEY_SECRET_FILE"
+sudo install -m 600 /dev/null "$THT_CA_SECRET_FILE"
+```
+
+Così ogni `sudo install` usa la variabile corretta e non si rischia di creare il file in un
+percorso diverso da quello che Compose leggerà. Se i secret sono forniti da un secret manager,
+si impostano le stesse variabili ai file materializzati dal manager e si saltano i comandi
+`install`.
+
 `install` è un comando Unix per creare/copiare un file impostando contestualmente i permessi.
 In `install -m 600 /dev/null DEST`:
 
@@ -76,6 +96,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.
 
+Dopo la creazione, scrivere il contenuto in ogni target (l'esempio seguente usa un file sorgente
+protetto; ripeterlo per le altre variabili):
+
+```sh
+sudo sh -c 'umask 077; cat > "$1"' sh "$THT_DWH_API_KEY_SECRET_FILE" \
+  < /percorso/protetto/dwh-api-key
+```
+
 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
@@ -110,11 +138,6 @@ 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
 ```