feat(cli): prepare and validate application documents offline

2026-09-28 16:33:07 +02:00
parent 64e6b9664a
commit b9c3369e7b
20 changed files with 1164 additions and 49 deletions
@@ -65,6 +65,99 @@ Il successo locale non certifica verità semantica, connettività o readiness. L
 revisione Git attivata in seguito deve contenere i documenti verificati; il comando
 non pubblica file non committati o directory vuote.

+## Predisporre e verificare i documenti applicativi
+
+Dopo la verifica dei workspace, creare una cartella locale **esterna al loro repository**:
+
+```sh
+tht installation prepare --directory ./mia-installazione
+```
+
+Il comando crea file privati commentati: `thothii-installation.yaml`, `operator.env`,
+`database-bootstrap.yaml` e `README.md`. La cartella deve essere nuova e il padre
+deve esistere. Non avvia servizi e non genera implicitamente password.
+
+1. Nel descrittore, scegliere modelli e provider. Il template propone
+   `openai/gpt-4.1-mini` per l'interazione e `ollama/qwen3-embedding:0.6b` con 1024
+   dimensioni per l'embedding. Sono valori modificabili, non una selezione richiesta
+   durante il setup. `modelCatalog.defaults.interaction` deve essere utilizzabile
+   nelle sessioni e anche nella generazione metadati, se quest'ultima è configurata.
+   Il template omette la generazione metadati, che è facoltativa. Consultare la
+   [configurazione dei modelli](../general/pi-configuration.md) per provider personalizzati.
+2. Sostituire il remoto Git sia nel descrittore sia in `operator.env`; mantenere
+   coerenti branch e trasporto. I percorsi sono assoluti e riferiti a questa macchina.
+   `operator.env` accetta una sola assegnazione letterale `KEY=value` per riga, senza
+   duplicati o interpolazioni shell. Le credenziali restano nei file referenziati.
+3. Compilare `database-bootstrap.yaml`: una voce per ciascun workspace, senza
+   duplicati. Questo esempio mostra il contratto completo di un collegamento diretto:
+
+   ```yaml
+   schemaVersion: 1
+   databases:
+     - workspaceId: pratica
+       engine: postgres
+       databaseName: vendite
+       schema: public
+       binding:
+         transport: postgres_direct
+         host: db.intranet
+         port: 5432
+         username: thoth_reader
+       secretFiles:
+         password: /percorso/privato/mia-installazione/secrets/database-password
+   ```
+
+   Usare le credenziali di un utente DWH in sola lettura. Per `rest_api`, il binding
+   richiede `baseUrl`, `restPath` e `restAuth` (`none`, `bearer`, `x-api-key`); quando
+   serve autenticazione, aggiungere `secretFiles.apiKey`. `ssh_tunnel` richiede
+   `username`, `sshHost`, `sshPort`, `sshUsername`, `sshTargetHost`, `sshTargetPort` e
+   i file `password`, `sshPrivateKey`, `sshKnownHosts`; abilita diagnostica Catalog,
+   non sessioni NL→SQL. Sono facoltativi `tlsCa` e `sshPrivateKeyPassphrase`.
+   Le Evidence HTTP firmate richiedono `evidenceSecretFiles` con chiave
+   `evidence.signed_urls`; S3 con credenziali statiche richiede `evidence.access_key`
+   e `evidence.secret_key`, con `evidence.session_token` facoltativo. Tutti i valori
+   sono percorsi di file privati. I workspace rimangono nello schema v4: il bootstrap
+   è un input iniziale, non un secondo Catalog runtime.
+4. Generare esplicitamente le credenziali tecniche nel layout standard:
+
+   ```sh
+   tht installation credentials --directory ./mia-installazione
+   ```
+
+   Sono creati password casuali separate per Catalog runtime/migrator e amministratore,
+   il relativo `auth/auth.yaml` con `auth/users.yaml`, un template `secrets/secrets.env`
+   e `secrets/pi-auth.json`. I file esistenti vengono conservati; se non validi, il
+   comando si ferma. L'amministratore iniziale è `admin`, la password è nel file
+   privato `secrets/admin-password` e non viene stampata. Il default è autenticazione
+   locale con URL pubblico `http://localhost:8080`: verificare e, se necessario,
+   modificare `auth/auth.yaml` prima del controllo. Questo incremento non valida il
+   bootstrap OIDC del percorso esistente.
+5. Inserire la chiave del provider in `secrets/secrets.env` e creare il file della
+   password DWH. Per HTTPS Git fornire i file referenziati per credenziali e CA:
+   credenziali vuote sono ammesse per un remoto pubblico, la CA deve essere disponibile.
+   Per SSH fornire chiave e known_hosts, scegliendo il relativo override nel descrittore.
+   I provider `pi_auth` richiedono credenziali Pi già preparate. Conservare tutti
+   questi file fuori dal repository workspace e proteggere l'accesso al solo utente
+   installatore (0600 su Unix, ACL equivalenti su Windows). Non committarli.
+6. Verificare e ripetere dopo ogni correzione:
+
+   ```sh
+   tht --installation /percorso/assoluto/mia-installazione/thothii-installation.yaml installation validate --workspaces /percorso/assoluto/miei-workspace --json
+   ```
+
+   Il bootstrap viene cercato accanto al descrittore; `--bootstrap PERCORSO` ne
+   seleziona uno diverso. Il controllo non cambia documenti, non genera proiezioni,
+   non usa la rete e non scrive database. Rifiuta placeholder, incoerenze, file
+   mancanti/non privati e segreti situati nel repository workspace. Il report indica
+   documento, campo e correzione senza valori riservati. Exit status: 0 successo
+   locale, 1 correzioni necessarie, 2 argomenti errati.
+
+Gli asset Compose standard del rilascio possono ancora mancare in questa fase;
+gli override personalizzati devono già esistere. Il report distingue i controlli
+differiti: asset del rilascio, connettività esterna, import Catalog e readiness.
+Un esito positivo prepara il successivo preflight: non autorizza a saltare tali
+controlli e non equivale a un'installazione completata.
+
 ## Prima di iniziare: i due repository

 Servono due repository distinti: