ThothII/docs/install/standalone-manual-it.md

Installazione standalone guidata

English version

Questa è la procedura per installare THothII da zero. THothII riceve una domanda in linguaggio naturale, interroga in sola lettura un database aziendale e accompagna l’utente nella revisione della SQL risultante. Il core, il catalogo PostgreSQL, Qdrant, il servizio di embedding e Pi vengono eseguiti in Docker; sul computer non servono Node.js, Python o Pi.

Preparazione e verifica dei workspace prima dello stack

I primi due passi del nuovo percorso funzionano senza Docker, Node, Python, Pi o un file di installazione. Usare il bundle della propria piattaforma con entrambi gli eseguibili tht e tht-workspace-documents nella stessa cartella (.exe su Windows). Aggiungere la cartella al PATH, oppure usare il percorso completo. Il vecchio pacchetto con il solo tht non contiene questa capacità. Il bundle è attualmente producibile dal manutentore; pubblicazione degli asset e immagini Docker Hub appartengono a una fase successiva. Il resto della guida descrive ancora il percorso di installazione esistente.

1. Scegliere una cartella nuova, esterna all'applicazione, con padre già esistente:

   tht workspace prepare --directory ./miei-workspace --id pratica --name "Pratica" --language it
   

   Sono creati thoth-workspaces.yaml, pratica/workspace.yaml e workspace-docs/pratica/README.md. Una destinazione esistente, anche vuota, viene rifiutata. Nessun servizio viene avviato; Git non viene inizializzato, nessun remoto viene contattato. I database di esempio restano un sottoprogetto differito. Per un repository fornito dal curatore, usare una copia locale separata e passare al punto 3: è sufficiente accesso in lettura all'origine.

2. Modificare con calma catalogo (schema v1) e descrittore workspace (schema v4). Mantenere uguali id, name e l'eventuale description nei due file; l'id deve coincidere con la cartella. Ogni cartella alla radice deve corrispondere a un workspace elencato, salvo workspace-docs e la directory locale .git. Connessioni, schema e credenziali dei database appartengono al Metadata Catalog dell'installazione. Le Evidence sono facoltative e inizialmente assenti.

3. Verificare, correggere il documento/campo indicato e ripetere:

   tht workspace validate --directory ./miei-workspace
   tht workspace validate --directory ./miei-workspace --json
   

   Su PowerShell usare gli stessi argomenti, ad esempio C:\ThothII\bin\tht.exe workspace validate --directory C:\ThothII\miei-workspace. Il controllo non modifica file. Rifiuta YAML multipli o malformati, chiavi/id duplicati, campi sconosciuti, incoerenze tra catalogo, cartelle e descrittori, riferimenti locali mancanti e link simbolici. Correggere il primo errore del documento e ripetere per vedere eventuali errori successivi.

Evidence absent è valido. Per filesystem si verificano directory, accessibilità e riferimenti letterali; per le selezioni Markdown standard anche i limiti dichiarati. Evidence v2 richiede curated/ e frontmatter con sintassi YAML valida. I limiti locali sono 1 MiB per documento letto e 100.000 elementi per albero Evidence. Pattern arbitrari, contratto completo delle unità curate, provenienza, accesso HTTP/S3 e indicizzazione restano controlli runtime espliciti. Vedere la guida Evidence.

Il JSON espone schema_version, scope: local-documents, ok, workspaces, issues e deferred_checks. I problemi riportano documento, campo, codice, correzione e, quando disponibile, riga YAML, senza stampare i valori del documento. Exit status: 0 successo locale, 1 documenti/accesso/bundle da correggere, 2 argomenti errati. Il successo locale non certifica verità semantica, connettività o readiness. La 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:

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 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:

   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:

   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:

   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.

Verificare le precondizioni e produrre il piano

Al passo 3, prima di completare tutti i parametri applicativi, controllare la macchina e la directory privata già preparata:

tht installation preflight --directory /percorso/installazione --json

Servono Docker Linux raggiungibile, Compose 2.24 o successivo, almeno 2 CPU, 4 GiB assegnati a Docker e 10 GiB liberi nella directory di installazione. Il rilascio può richiedere risorse maggiori. Su Windows eseguire il binario Linux in Ubuntu WSL2 con integrazione Docker Desktop; Pi è incluso nell'immagine core.

Al passo 5, dopo installation validate, selezionare il manifest del rilascio pubblicato, con le risorse del bundle già scaricate, e produrre un piano nuovo:

tht --installation /percorso/installazione/thothii-installation.yaml installation plan \
  --workspaces /percorso/workspaces \
  --release /percorso/rilascio/release-manifest.json \
  --output /percorso/installazione/installation-plan.json --json

Il comando ripete i controlli dei documenti, verifica immagini/digest e Compose, Git, database ed Evidence esterne disponibili, poi salva il piano e il suo file privato .key. Non esegue il setup. Le immagini assenti e le dipendenze esterne irraggiungibili bloccano il piano. Al momento la pubblicazione reale Docker Hub è ancora il ticket successivo: un manifest inventato non permette di aggirarla.

Correggere gli esiti error; leggere gli warning. Gli esiti deferred-to-runtime identificano controlli obbligatori dopo l'avvio, non una readiness già ottenuta. Un piano valido non sostituisce questi gate. Dopo una correzione o rotazione di credenziali produrre un nuovo piano; i file esistenti non vengono sovrascritti. Conservare piano e chiave fuori dal Git dei workspace. Le prove esterne sono letture limitate: autenticazione/schema del database, letture Git e HTTP/S3, raggiungibilità degli endpoint modello espliciti. Nessuna generazione LLM viene invocata; le richieste HTTP/S3 possono avere i normali costi del servizio. Limiti, manifest e obblighi sono nel riferimento di preflight.

Prima di iniziare: i due repository

Servono due repository distinti:

1. il repository dell’applicazione, che l’utente clona: https://git.tylconsulting.it/mptyl/ThothII.git;
2. il repository dei workspace, indicato dal curatore/installatore. Non è il repository di THothII e non va clonato manualmente nella directory dell’applicazione.

Il repository workspace contiene il catalogo e una directory per ogni workspace, normalmente:

thoth-workspaces.yaml
<workspace-id>/workspace.yaml
<workspace-id>/evidence/**       # se il workspace dichiara Evidence

Il file workspace.yaml descrive identità, lingua e, opzionalmente, la sorgente Evidence. Per scelta architetturale non contiene password del database. L’identità del database, il trasporto (PostgreSQL, REST o tunnel), username, password, token e certificati sono configurazione locale dell’installazione, conservata cifrata dal Catalog. Questo evita di committare credenziali nel repository workspace.

0. Prerequisiti della macchina

Windows

• Windows 10/11 con Docker Desktop avviato e backend WSL2 abilitato.
• Ubuntu in WSL2, con integrazione Docker Desktop abilitata per quella distribuzione.
• Git, Bash, curl, OpenSSL e shasum nella distribuzione WSL2.
• Non installare Node.js, Python o Pi sull’host per questa procedura.

In PowerShell, se WSL2 non esiste ancora, usare la procedura aziendale oppure:

wsl --install -d Ubuntu

Eseguire poi tutti i comandi dentro Ubuntu WSL2, in una directory Linux come $HOME/src, non sotto /mnt/c. Il percorso nativo scripts/install-tht.ps1 esiste per scenari PowerShell avanzati; per la prova riproducibile usare WSL2.

macOS

• Docker Desktop installato, avviato e con alcuni GB liberi per immagini e modello di embedding.
• Git, Bash, curl, OpenSSL e shasum.
• Sono supportati Mac Intel e Apple Silicon se Docker Desktop supporta l’architettura restituita dal Docker server.
• Non installare Node.js, Python o Pi sull’host per questa procedura.

Linux, incluso Omarchy

• Git, Bash, curl, OpenSSL e shasum.
• Docker Engine e il plugin Docker Compose v2. Su Omarchy verificare prima:

command -v docker
docker compose version
docker info

Se Docker manca, installare Docker e Compose con il gestore pacchetti/procedura approvata dalla distribuzione, poi avviare il servizio. Su una distribuzione Arch-like il percorso tipico è:

sudo pacman -S docker docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

Dopo l’aggiunta al gruppo aprire una nuova sessione e ripetere docker info. Non installare Node.js, Python o Pi sull’host: sono dentro le immagini Docker.

Su tutti i sistemi il controllo finale è:

bash scripts/check-standalone-prerequisites.sh
docker version --format '{{.Server.Arch}}'

L’architettura deve essere amd64, x86_64, arm64 o aarch64. Servono inoltre accesso al repository Gitea dell’applicazione, URL/branch e credenziali del repository workspace, raggiungibilità dal container degli endpoint DWH/LLM e le credenziali, token o certificati associati ai database.

1. Cosa clonare

Clonare solo l’applicazione:

mkdir -p "$HOME/src"
cd "$HOME/src"
git clone https://git.tylconsulting.it/mptyl/ThothII.git
cd ThothII
git rev-parse --short HEAD

Annotare la revisione. Il repository workspace verrà scaricato da tht setup --complete dentro un volume Docker persistente, usando URL, branch e trasporto indicati durante il setup.

2. Installare il comando terminale

Dal root del clone:

bash scripts/check-standalone-prerequisites.sh
mkdir -p "$HOME/.local/bin"
THT_INSTALL_DIRECTORY="$HOME/.local/bin" bash scripts/install-tht.sh
export PATH="$HOME/.local/bin:$PATH"
tht version

Il comando tht è l’unico componente nativo da installare. Costruisce il binario con Docker e orchestra Compose; non è un secondo runtime dell’applicazione.

3. Preparare pochi segreti e avviare il setup completo

La prima esecuzione crea i placeholder protetti sotto deploy/local/secrets/ e si ferma se manca una credenziale necessaria. Compilare i file indicati e rilanciare lo stesso comando: i file di configurazione già compatibili vengono riutilizzati.

tht setup --complete --profile local --shell-mode full --shell-default-locale en

Durante il setup servono solo le informazioni operative che il computer non può conoscere:

Richiesta	Cosa inserire
Repository workspace	URL del repository dati/configurazione, non ThothII.git
Branch	normalmente main
Accesso	ssh con chiave e known_hosts, oppure https con credential file e CA
DWH/LLM URL	endpoint senza token nella URL
Login locale	utente e password iniziale richiesti dal prompt

Il setup crea automaticamente le password casuali del Catalog e le scrive in operator.env come percorsi, non come valori. Esegue docker compose config, costruisce le immagini, avvia il Catalog, esegue catalog-migrate, avvia lo stack e importa il repository workspace. L’import attiva anche l’Evidence dichiarata: almeno i file source presenti nel workspace vengono materializzati nel registro locale.

Il file da compilare

Il file principale è:

deploy/local/secrets/thothii.secrets

Inserire solo righe NOME=VALORE necessarie al modelCatalog e agli adapter, per esempio una API key LLM (DEEPSEEK_API_KEY, OPENAI_API_KEY o quella dichiarata dal catalogo) ed eventualmente THT_DWH_API_KEY. I nomi ammessi sono documentati in deploy/secrets/README.md. Non mettere token nelle URL, nel repository o nei comandi.

Due precisazioni evitano gli errori più comuni:

• se il catalogo usa pi_auth, il token LLM va nel file Pi pi-auth.json creato dal setup; {} è solo un placeholder e non abilita alcun modello;
• le credenziali specifiche di un database workspace (password PostgreSQL, API token REST, chiave SSH del tunnel, known_hosts, CA) non vanno nel repository workspace: si inseriscono per workspace in Database Management, che le conserva nel Catalog cifrato. Il workspace indica database/schema e trasporto; l’installatore deve ottenere dal proprietario il valore corretto.

Per un repository workspace privato sono inoltre indispensabili i file Git richiesti dal trasporto: una chiave SSH e known_hosts, oppure credential file HTTPS e CA. Sono file di trasporto, non un secondo bundle da committare. Per ridurre i file da compilare, usare SSH con una deploy key già autorizzata.

4. Controlli automatici e test da terminale

Il setup verifica file, permessi, descriptor, Compose, Docker, autenticazione, servizi, Pi e workspace. Dopo l’avvio usare questi comandi in qualunque momento:

INSTALLATION="$PWD/deploy/local/thothii-installation.yaml"
tht --installation "$INSTALLATION" doctor --json
tht --installation "$INSTALLATION" workspace pull --json
tht --installation "$INSTALLATION" workspace test --json

workspace test prova, per ogni workspace attivo, il binding del database e le credenziali, Evidence, Qdrant e il servizio embedding. Restituisce exit code diverso da zero se manca il binding del database o una connessione non è utilizzabile. Prima di eseguirlo l’installatore deve aver configurato il database in Database Management: il workspace repository da solo non può contenere la password.

Per una verifica generale del core, doctor --json è il test ripetibile e non distruttivo. Il test funzionale finale deve inoltre aprire http://127.0.0.1:8080, autenticarsi e completare una domanda reale fino alla SQL finale.

Attività che può svolgere solo l’installatore

La procedura automatizza il bootstrap, non può inventare decisioni o autorizzazioni aziendali. L’installatore deve completare e registrare:

1. quali LLM sono utilizzabili, il relativo modelCatalog e le API key collegate; poi eseguire tht pi test e tht doctor;
2. per ogni database: configurazione, test connessione, sincronizzazione dello schema e generazione delle descrizioni;
3. consolidamento umano delle descrizioni generate;
4. generazione delle entry semantiche in Qdrant tramite workspace preprocess run;
5. generazione delle FK suggerite dal naming, come complemento alle FK lette dallo schema, revisione umana delle proposte e caricamento delle relazioni approvate in Qdrant;
6. verifica periodica con tht doctor --json e tht workspace test --json;
7. una domanda reale completata con successo, senza errori di connessione o modello.

La configurazione è dichiarata completa solo quando tutti i punti applicabili sono stati eseguiti, le decisioni sono state registrate e i due test terminali sono verdi. Il core è dichiarato usabile solo dopo la domanda reale, non perché il frontend risponde a /health.

Gate A e Gate B

Gate A — piattaforma

uname -a
docker version --format '{{.Server.Version}} {{.Server.Arch}}'
tht version
bash scripts/check-standalone-prerequisites.sh
bash scripts/verify-standalone-install.sh "$INSTALLATION"

Gate B — usabilità

tht --installation "$INSTALLATION" doctor --json
tht --installation "$INSTALLATION" workspace test --json
curl --fail --silent --show-error http://127.0.0.1:8080/health

Poi eseguire una domanda reale e fermare/riavviare con tht stop e tht start. Non usare docker compose down --volumes: cancella Catalog, sessioni, Qdrant e il modello embedding.

Diagnosi rapida

Sintomo	Azione
Docker Engine is not reachable	avviare Docker Desktop o systemctl e ripetere docker info
Omarchy non trova docker	installare Docker/Compose, abilitare il servizio e riaprire la sessione
Windows vede Docker ma Bash fallisce	usare Ubuntu WSL2 e abilitarne l’integrazione in Docker Desktop
pull workspace fallisce	controllare URL, branch, chiave/credential file e known_hosts dal container
workspace test segnala binding mancante	configurare database, token/password e CA in Database Management
Pi non è pronto	compilare pi-auth.json o la chiave dichiarata dal modelCatalog, poi eseguire tht pi test

Documenti collegati

• Installazione e primo avvio
• Operazioni sui workspace
• Database Management
• Configurazione dei modelli
• deploy/secrets/README.md

La pubblicazione di immagini su Docker Hub e gli installer nativi DMG/MSI/AppImage restano attività successive: questa procedura parte dal clone Gitea e non richiede immagini Docker Hub pre-pubblicate.