# 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.