Design: configurazione Docker semplificata

Obiettivo

Ridurre l'installazione a un file di configurazione .env interno al clone e a un solo file contenente tutti i secret, mantenendo il comando operativo standard:

docker compose up --build -d

Il comportamento di default deve essere determinato dai file presenti nella directory radice ThothII/, senza obbligare l'operatore a ricordare -f, --env-file o profili Compose.

Struttura installativa

ThothII/
├── .env                         # configurazione non segreta e default Compose
├── .env.example                 # template versionato
├── compose.yaml                 # file Compose principale, usabile senza -f
├── deploy/
│   ├── secrets/thothii.secrets  # unico file secret, escluso da Git
│   └── workspaces/              # workspace YAML versionati
└── data/                        # dati persistenti solo se bind mount esplicito

.env contiene host, endpoint, profilo scelto, COMPOSE_FILE, COMPOSE_PROFILES e il percorso del bundle secret. Non contiene valori secret. Il file viene creato copiando .env.example e rimane nella directory ThothII/.

Il bundle deploy/secrets/thothii.secrets usa righe NOME=VALORE, con nomi documentati e validazione rigorosa. Non sono ammesse espansioni shell, comandi, URL con credenziali o righe duplicate. Il file deve essere 0600 sull'host e viene montato read-only nei soli servizi che ne hanno bisogno.

Default Compose

compose.yaml diventa il file principale per il profilo applicativo esterno: core e frontend non sono nascosti dietro un profilo obbligatorio. Il .env seleziona eventuali overlay tramite la variabile Compose standard COMPOSE_FILE e il profilo tramite COMPOSE_PROFILES.

Esempi:

server con DWH/vector esterni: COMPOSE_FILE=compose.yaml:deploy/compose.production.yaml;
Mac/Windows con pgvector locale: COMPOSE_FILE=compose.yaml:deploy/compose.local-vector.yaml e COMPOSE_PROFILES=local-vector;
preprocessing locale: aggiunta dell'overlay preprocess nel valore COMPOSE_FILE.

Quando .env è configurato, il comando non cambia tra i contesti:

docker compose up --build -d

I comandi con -f e --env-file restano documentati solo come override diagnostico, non come percorso normale di installazione.

Bundle secret e runtime

Il core riceve THT_SECRETS_FILE=/run/secrets/thothii.secrets. Un loader comune:

apre il bundle con O_NOFOLLOW, verifica owner, permessi e inode;
rifiuta chiavi sconosciute, duplicate, vuote o provider composti non supportati;
espone i singoli valori solo in memoria al componente che ne ha bisogno;
non stampa il bundle, non lo inserisce in settings.json, argv, health o log.

Per pgvector locale, il servizio di inizializzazione e le migrazioni usano lo stesso loader; non si creano più file bootstrap, reader, writer e migrator. Le password non vengono passate come argomenti URL. I workspace ricevono riferimenti logici al secret bundle, mai valori.

La compatibilità temporanea con le variabili THT_*_SECRET_FILE viene mantenuta come fallback esplicito per installazioni già esistenti, ma il template e la documentazione nuovi usano solo THT_SECRETS_FILE.

Compatibilità e sicurezza

docker compose config --quiet deve funzionare dalla radice senza opzioni aggiuntive;
il default non deve avviare pgvector locale se il .env seleziona servizi esterni;
i profili local-vector e preprocess devono aggiungere solo i servizi necessari;
il bundle secret deve essere escluso da .gitignore e dai build context Docker;
errori di secret mancanti o non validi devono terminare prima dell'avvio applicativo, con messaggi sanitizzati;
i test devono coprire sia il percorso standard docker compose up --build -d sia gli override legacy con file secret separati.

Verifica prevista

La verifica finale comprende:

rendering Compose del default e dei quattro preset .env.example;
test unitari del parser bundle e della compatibilità legacy;
build delle immagini core/frontend;
smoke health/SSE/persistenza;
smoke local-vector con un solo bundle e migrazioni;
smoke preprocess con il default selezionato dal .env;
controllo che nessun secret compaia in docker compose config, log, argv o immagini.

4.3 KiB Raw Blame History