# Installazione standalone guidata [English version](standalone-manual-en.md) 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: ```sh 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: ```sh 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](../evidence.md). 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**: ```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. ## 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: ```bash 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: ```bash 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](installation-preflight.md). ## 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.yaml /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](first-start.md) - [Operazioni sui workspace](../operations/workspaces.md) - [Database Management](../operations/database-management.md) - [Configurazione dei modelli](../general/pi-configuration.md) - 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.