11 KiB
Installazione standalone guidata
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:
- il repository dell’applicazione, che l’utente clona: https://git.tylconsulting.it/mptyl/ThothII.git;
- 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:
- quali LLM sono utilizzabili, il relativo modelCatalog e le API key collegate; poi eseguire tht pi test e tht doctor;
- per ogni database: configurazione, test connessione, sincronizzazione dello schema e generazione delle descrizioni;
- consolidamento umano delle descrizioni generate;
- generazione delle entry semantiche in Qdrant tramite workspace preprocess run;
- generazione delle FK suggerite dal naming, come complemento alle FK lette dallo schema, revisione umana delle proposte e caricamento delle relazioni approvate in Qdrant;
- verifica periodica con tht doctor --json e tht workspace test --json;
- 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.