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

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