263 lines
11 KiB
Markdown
263 lines
11 KiB
Markdown
# 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.
|
||
|
||
## 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.
|