From a6b195b8ae6e98aa1eca21e62f8d28099280c36c Mon Sep 17 00:00:00 2001
From: mptyl <mp@tylconsulting.it>
Date: Sun, 12 Jul 2026 10:54:42 +0200
Subject: [PATCH] docs: design simplified Docker configuration

---
 .../2026-07-12-simple-docker-config-design.md | 98 +++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-12-simple-docker-config-design.md

diff --git a/docs/superpowers/specs/2026-07-12-simple-docker-config-design.md b/docs/superpowers/specs/2026-07-12-simple-docker-config-design.md
new file mode 100644
index 00000000..33fe2a46
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-12-simple-docker-config-design.md
@@ -0,0 +1,98 @@
+# 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:
+
+```sh
+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
+
+```text
+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:
+
+```sh
+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:
+
+1. apre il bundle con `O_NOFOLLOW`, verifica owner, permessi e inode;
+2. rifiuta chiavi sconosciute, duplicate, vuote o provider composti non supportati;
+3. espone i singoli valori solo in memoria al componente che ne ha bisogno;
+4. 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:
+
+1. rendering Compose del default e dei quattro preset `.env.example`;
+2. test unitari del parser bundle e della compatibilità legacy;
+3. build delle immagini core/frontend;
+4. smoke health/SSE/persistenza;
+5. smoke local-vector con un solo bundle e migrazioni;
+6. smoke preprocess con il default selezionato dal `.env`;
+7. controllo che nessun secret compaia in `docker compose config`, log, argv o immagini.