330 lines
15 KiB
Markdown
330 lines
15 KiB
Markdown
# Installazione manuale standalone
|
||
|
||
[English version](standalone-manual-en.md)
|
||
|
||
Questa è la procedura di prova per predisporre THothII come applicazione autonoma in modalità
|
||
`full` su macOS, Windows e Linux.
|
||
|
||
In questo documento “autonoma” significa che l’utente non deve installare Node.js, Python o Pi
|
||
sull'host: i servizi applicativi e i servizi semantici
|
||
locali vengono eseguiti con Docker. DWH e provider LLM restano endpoint esterni configurati
|
||
dall’installazione; questa procedura non è un pacchetto offline.
|
||
|
||
Il percorso non usa installer grafici, launcher nativi o immagini Docker Hub. Si parte da un clone
|
||
Gitea e si usano comandi espliciti da terminale. La pubblicazione di immagini pre-costruite è una
|
||
fase successiva.
|
||
|
||
## Matrice di verifica
|
||
|
||
| Sistema | Terminale raccomandato | Runtime | Architettura della prova |
|
||
| --- | --- | --- | --- |
|
||
| macOS supportato dalla versione Docker Desktop installata | Bash nel Terminale | Docker Desktop | Apple Silicon (`arm64`) |
|
||
| Windows 11 | Ubuntu dentro WSL2 | Docker Desktop con integrazione WSL2 | x64 (`amd64`) |
|
||
| Linux Ubuntu 22.04 o 24.04 | Bash | Docker Engine + Compose v2 | x64 (`amd64`) |
|
||
|
||
Intel macOS non fa parte della prima campagna di verifica. ARM Linux può essere provato quando il
|
||
runtime Docker della macchina restituisce `arm64`, ma non è un requisito della matrice minima.
|
||
|
||
Le verifiche documentali e dei prerequisiti Mac sono passate. Le installazioni complete da zero
|
||
sui tre sistemi restano da eseguire: la matrice indica le prove previste, non una certificazione.
|
||
|
||
## Cosa serve prima di iniziare
|
||
|
||
Servono:
|
||
|
||
- accesso al repository Gitea di THothII e al repository Git dei workspace;
|
||
- Git;
|
||
- Docker Desktop su macOS e Windows, oppure Docker Engine con il plugin Compose v2 su Linux;
|
||
- Bash, `curl`, OpenSSL e `shasum` (su Ubuntu, pacchetto `libdigest-sha-perl`);
|
||
- spazio disco sufficiente per compilare le immagini e scaricare il modello di embedding;
|
||
- gli endpoint DWH e LLM, più le credenziali che l’installazione deve usare.
|
||
|
||
Su Linux l’utente corrente deve poter eseguire Docker. Se il sistema richiede `sudo`, aggiungere
|
||
l’utente al gruppo Docker secondo la policy locale e aprire una nuova sessione prima di continuare.
|
||
|
||
Su Windows usare Ubuntu in WSL2 per tutti i comandi di questa guida. In Docker Desktop attivare
|
||
l’integrazione WSL2 per quella distribuzione. Clonare il progetto nel filesystem Linux di WSL2,
|
||
per esempio sotto `~/src`, e non sotto `/mnt/c`: si evitano rallentamenti e problemi di permessi o
|
||
line ending. Non è necessario installare Pi sull’host.
|
||
|
||
Verificare il runtime prima del clone o subito dopo:
|
||
|
||
```sh
|
||
docker version
|
||
docker compose version
|
||
docker version --format '{{.Server.Arch}}'
|
||
```
|
||
|
||
L’ultima istruzione deve restituire `amd64`, `x86_64`, `arm64` o `aarch64`.
|
||
|
||
## 1. Clonare una revisione del progetto
|
||
|
||
Usare il repository di progetto su Gitea:
|
||
|
||
```sh
|
||
mkdir -p "$HOME/src"
|
||
cd "$HOME/src"
|
||
git clone https://git.tylconsulting.it/mptyl/ThothII.git
|
||
cd ThothII
|
||
git rev-parse --short HEAD
|
||
```
|
||
|
||
Per un clone SSH usare, se la chiave è già autorizzata su Gitea:
|
||
|
||
```sh
|
||
git clone git@git.tylconsulting.it:mptyl/ThothII.git
|
||
```
|
||
|
||
Per una prova ripetibile annotare l’hash stampato da `git rev-parse`. In una campagna successiva
|
||
usare la revisione/tag approvata dal maintainer invece di seguire implicitamente una `main` che
|
||
può cambiare.
|
||
|
||
## 2. Verificare i prerequisiti e installare il comando operatore
|
||
|
||
Dal root del clone:
|
||
|
||
```sh
|
||
bash scripts/check-standalone-prerequisites.sh
|
||
export PATH="$HOME/.local/bin:$PATH"
|
||
THT_INSTALL_DIRECTORY="$HOME/.local/bin" bash scripts/install-tht.sh
|
||
tht version
|
||
```
|
||
|
||
`install-tht.sh` è un bootstrap del solo comando operatore nativo `tht`; non installa una versione
|
||
desktop di THothII. Usa il builder Docker del repository, installa il binario adatto all’ambiente
|
||
del terminale e lo installa nella directory utente. Aggiungere `$HOME/.local/bin` al PATH della
|
||
shell anche per i terminali successivi. Un `tht` già presente in quella directory viene aggiornato.
|
||
|
||
Su Windows, eseguire questi comandi dentro WSL2. Il binario `tht` installato è quello Linux di WSL2;
|
||
il runtime dell’applicazione rimane Docker Desktop. Non usare `scripts/install-tht.ps1` come percorso
|
||
principale di questa prova.
|
||
|
||
## 3. Configurare e avviare l’installazione locale
|
||
|
||
Eseguire i blocchi successivi nella stessa sessione Bash dal root fisico del clone (`pwd -P`).
|
||
Creare prima le due password distinte del catalogo, conservando eventuali file già esistenti:
|
||
|
||
```bash
|
||
umask 077
|
||
mkdir -p deploy/local/secrets
|
||
for name in catalog-runtime-password catalog-migrator-password; do
|
||
target="deploy/local/secrets/$name"
|
||
if [ ! -e "$target" ]; then
|
||
(set -C; openssl rand -hex 32 > "$target") || exit 1
|
||
fi
|
||
done
|
||
export THT_CATALOG_RUNTIME_PASSWORD_SOURCE="$(pwd -P)/deploy/local/secrets/catalog-runtime-password"
|
||
export THT_CATALOG_MIGRATOR_PASSWORD_SOURCE="$(pwd -P)/deploy/local/secrets/catalog-migrator-password"
|
||
```
|
||
|
||
Non rigenerare le password di un catalogo già inizializzato. Configurare senza avviare i servizi:
|
||
|
||
```sh
|
||
tht setup --profile local --shell-mode full --shell-default-locale en --configure-only
|
||
```
|
||
|
||
Rispondere ai prompt nel seguente modo:
|
||
|
||
| Prompt | Valore o regola |
|
||
| --- | --- |
|
||
| Installation ID | `local`, salvo necessità di più installazioni nello stesso clone |
|
||
| Deployment profile | `local` |
|
||
| DWH API endpoint | URL `http(s)` senza user, password, query o fragment; può restare vuoto per il solo smoke test |
|
||
| LLM API endpoint | URL `http(s)` senza credenziali; può restare vuoto per il solo smoke test |
|
||
| Workspace repository URL | URL del repository dei workspace, non il clone sorgente di THothII |
|
||
| Workspace branch | normalmente `main` |
|
||
| Workspace access | `ssh` se si usa una chiave deploy; altrimenti `https` con credential file protetto |
|
||
| Percorsi dei file | accettare i percorsi predefiniti sotto `deploy/local/secrets/` nella prima prova |
|
||
| Secret templates | rispondere `yes` quando i file protetti non esistono ancora |
|
||
| Autenticazione | configurare il login locale richiesto dall’installazione; non inserire password in una riga di comando |
|
||
|
||
La configurazione generata è locale e ignorata da Git:
|
||
|
||
```text
|
||
deploy/local/thothii-installation.yaml
|
||
deploy/local/operator.env
|
||
deploy/local/auth/
|
||
deploy/local/secrets/
|
||
```
|
||
|
||
Modificare i segreti solo nei file locali protetti; non committarli. Il file `deploy/env/local.env.example` è un riferimento
|
||
tracciato; il percorso generato da `tht setup`, `deploy/local/operator.env`, è quello da usare per
|
||
questa installazione.
|
||
|
||
### Completare i file protetti
|
||
|
||
Se il setup ha creato template vuoti, inserire i valori con un editor locale:
|
||
|
||
```sh
|
||
chmod 600 deploy/local/secrets/*
|
||
"${EDITOR:-vi}" deploy/local/secrets/thothii.secrets
|
||
```
|
||
|
||
Il bundle deve contenere solo righe `KEY=VALUE` per le credenziali effettivamente usate dal
|
||
`modelCatalog`. I nomi ammessi e il confine delle credenziali sono descritti nel file locale
|
||
`deploy/secrets/README.md`. Non mettere token nelle URL, nel
|
||
descriptor YAML, nel repository Git o nei comandi copiati nella shell.
|
||
|
||
Per accesso workspace SSH, predisporre anche la chiave privata e il file `known_hosts` indicati dal
|
||
setup. Per accesso HTTPS, predisporre il credential file Git e l’eventuale CA. Entrambi devono
|
||
restare protetti e fuori dal controllo versione.
|
||
|
||
Prima dell'avvio completare anche questi passaggi:
|
||
|
||
1. Aggiungere `THT_CATALOG_RUNTIME_PASSWORD_SOURCE` e `THT_CATALOG_MIGRATOR_PASSWORD_SOURCE` a
|
||
`deploy/local/operator.env`, con gli stessi percorsi assoluti esportati sopra. Il setup non salva
|
||
queste due variabili. Inserire i percorsi, non le password.
|
||
2. Sostituire il `modelCatalog` generico nel descriptor con la configurazione provider/modelli
|
||
approvata. I default generati non replicano il Mac esistente. Vedere [configurazione Pi/modelli](../general/pi-configuration.md)
|
||
e l'esempio locale `deploy/psd/thothii-installation.yaml.example`.
|
||
3. Inserire in `thothii.secrets` le chiavi referenziate da `authentication.apiKeyEnv`. I provider
|
||
`pi_auth` richiedono credenziali valide nel file `PI_AUTH_FILE`; il template `{}` non autentica.
|
||
4. Completare i file Git del workspace. SSH richiede una chiave deploy autorizzata e known-hosts
|
||
verificato; HTTPS richiede il credential file e il bundle CA previsti dall'overlay. I template
|
||
vuoti non consentono l'accesso al repository.
|
||
|
||
Dopo aver modificato la configurazione generata, non rilanciare setup: rifiuta file esistenti con
|
||
contenuti diversi. Generare le proiezioni ed eseguire la migrazione esplicita indicata sotto.
|
||
Impostare `THT_GIT_ACCESS=https` se scelto nel setup. Il blocco usa il nuovo descriptor `local`
|
||
con il solo overlay Git; per installazioni personalizzate includere gli overlay aggiuntivi
|
||
nello stesso ordine del descriptor.
|
||
|
||
```bash
|
||
INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
|
||
tht --installation "$INSTALLATION" installation generate
|
||
THT_PROJECT="thothii-$(printf '%s' "$INSTALLATION" | shasum -a 256 | cut -c 1-12)"
|
||
THT_GIT_ACCESS=ssh
|
||
compose=(
|
||
docker compose --project-name "$THT_PROJECT" --project-directory "$(pwd -P)"
|
||
--env-file "$(pwd -P)/deploy/local/operator.env"
|
||
-f compose.yaml -f deploy/compose.local.yaml
|
||
-f "deploy/compose.git-$THT_GIT_ACCESS.yaml"
|
||
-f deploy/local/generated/compose.models.yaml
|
||
)
|
||
"${compose[@]}" config --quiet
|
||
"${compose[@]}" build core frontend
|
||
"${compose[@]}" up -d catalog-db
|
||
"${compose[@]}" run --rm catalog-migrate
|
||
tht --installation "$INSTALLATION" start
|
||
```
|
||
|
||
Fermarsi se un comando fallisce. Il nome progetto coincide con l'hash usato da `tht`, preservando
|
||
l'identità dei volumi. `catalog-migrate` applica le migrazioni Catalog e Memory; `tht start` non
|
||
lo esegue automaticamente. Il primo download del modello embedding può richiedere tempo.
|
||
Usare questa sequenza legata all'installazione, non `run-stack.sh` con env/progetto diversi.
|
||
|
||
## 4. Verificare l’installazione
|
||
|
||
Il descriptor generato per l’ID predefinito è:
|
||
|
||
```sh
|
||
INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
|
||
test -f "$INSTALLATION"
|
||
bash scripts/verify-standalone-install.sh "$INSTALLATION"
|
||
```
|
||
|
||
Il verificatore è read-only: esegue `tht doctor --json` e `tht status`, senza ristartare lo stack,
|
||
rigenerare la configurazione o stampare il contenuto dei segreti.
|
||
|
||
### Gate A — smoke di piattaforma, su tutti e tre i computer
|
||
|
||
Registrare per ogni macchina:
|
||
|
||
```sh
|
||
uname -a
|
||
docker version --format '{{.Server.Version}} {{.Server.Arch}}'
|
||
tht version
|
||
bash scripts/check-standalone-prerequisites.sh
|
||
bash scripts/verify-standalone-install.sh "$INSTALLATION"
|
||
```
|
||
|
||
Il gate passa quando il clone è integro, Docker e Compose sono raggiungibili, `tht doctor` è OK,
|
||
lo stack è avviato e il frontend risponde sulla porta locale predefinita `http://127.0.0.1:8080`.
|
||
Il doctor controlla anche workspace e Pi: registrare separatamente i loro errori senza attribuire
|
||
ogni fallimento alla piattaforma. Verificare la disponibilità HTTP con:
|
||
|
||
```sh
|
||
curl --fail --silent --show-error http://127.0.0.1:8080/health
|
||
```
|
||
|
||
### Gate B — verifica funzionale
|
||
|
||
Eseguire almeno su una macchina con endpoint e credenziali disponibili:
|
||
|
||
Seguire prima [Workspace operations](../operations/workspaces.md) per importare/preparare il
|
||
workspace e configurare Database e binding locale. Il clone sorgente non trasferisce catalogo,
|
||
segreti o sessioni del Mac. Connettere l'eventuale VPN richiesta da DWH/modelli e verificare
|
||
che i relativi nomi siano raggiungibili anche dai container.
|
||
|
||
1. aprire `http://127.0.0.1:8080`;
|
||
2. autenticarsi con l’account locale configurato;
|
||
3. verificare che il workspace configurato sia leggibile;
|
||
4. avviare una domanda reale e completare i gate di revisione fino alla SQL finale;
|
||
5. fermare e riavviare l’installazione, poi ripetere `verify-standalone-install.sh`.
|
||
|
||
Un fallimento del Gate B per DWH, provider LLM, Git workspace o credenziali non dimostra da solo un
|
||
problema di portabilità Docker: registrare separatamente l’endpoint o il componente fallito.
|
||
|
||
## Ciclo di vita quotidiano
|
||
|
||
Usare il descriptor esplicito quando più installazioni possono essere scoperte:
|
||
|
||
```sh
|
||
INSTALLATION="$PWD/deploy/local/thothii-installation.yaml"
|
||
|
||
tht --installation "$INSTALLATION" status
|
||
tht --installation "$INSTALLATION" start
|
||
tht --installation "$INSTALLATION" start --build
|
||
tht --installation "$INSTALLATION" logs
|
||
tht --installation "$INSTALLATION" doctor --json
|
||
tht --installation "$INSTALLATION" stop
|
||
```
|
||
|
||
`start --build` è necessario dopo una modifica al codice o per ricostruire le immagini dal clone
|
||
corrente. `stop` conserva volumi, sessioni, catalogo, stato Pi, dati Qdrant e modello embedding.
|
||
Non usare `docker compose down --volumes` durante una prova normale: è un’operazione distruttiva
|
||
che cancella i dati locali.
|
||
Per aggiornamenti che richiedono migrazioni, seguire il runbook della release prima dell'avvio.
|
||
|
||
## Diagnosi rapida
|
||
|
||
| Sintomo | Controllo |
|
||
| --- | --- |
|
||
| `Docker Engine is not reachable` | avviare Docker Desktop oppure il servizio Docker e ripetere `docker info` |
|
||
| Windows vede Docker ma Bash fallisce | eseguire la guida dentro Ubuntu WSL2 e abilitare l’integrazione della distribuzione in Docker Desktop |
|
||
| `tht: command not found` | aprire una nuova shell e verificare `command -v tht`; se necessario ripetere il bootstrap |
|
||
| line ending o script non eseguibile | usare un clone nel filesystem WSL2/Linux e rieseguire `bash scripts/...` |
|
||
| architettura non supportata | verificare `docker version --format '{{.Server.Arch}}'`; la prova richiede `amd64` o `arm64` |
|
||
| descriptor o env file mancanti | usare il percorso `deploy/local/...` generato da `tht setup`, non un file copiato casualmente |
|
||
| stack sano ma workflow fallisce | controllare separatamente URL, credential bundle, workspace Git e autenticazione |
|
||
| dati apparentemente persi | verificare che non sia stato usato `down --volumes`; `stop` non rimuove i volumi |
|
||
|
||
## Checklist di accettazione
|
||
|
||
- [ ] Il clone proviene dal repository Gitea atteso e la revisione è stata annotata.
|
||
- [ ] Docker Desktop/Engine e Compose v2 sono disponibili.
|
||
- [ ] Il runtime restituisce un’architettura ammessa.
|
||
- [ ] `tht` è stato costruito dal repository e risponde a `tht version`.
|
||
- [ ] Il setup usa `profile: local`, `shell.mode: full` e `shell.defaultLocale: en`.
|
||
- [ ] Descriptor, `operator.env`, autenticazione e segreti sono presenti solo in `deploy/local/`.
|
||
- [ ] Nessun segreto compare in Git, URL, YAML pubblico o comandi registrati.
|
||
- [ ] Gate A superato su macOS Apple Silicon, Windows WSL2/x64 e Linux x64.
|
||
- [ ] Gate B eseguito almeno su una macchina con DWH e LLM disponibili.
|
||
- [ ] Stop/start e verifica finale completati senza cancellare i volumi.
|
||
|
||
## Fuori perimetro di questa release
|
||
|
||
Restano attività successive:
|
||
|
||
- pubblicare immagini pre-costruite su Docker Hub;
|
||
- ridurre ulteriormente i prompt tramite una configurazione non interattiva dedicata;
|
||
- creare pacchetti DMG, MSI/EXE, AppImage o altri installer nativi;
|
||
- fornire un runtime offline o un DWH/LLM locale incluso nell’applicazione.
|
||
|
||
## Documenti collegati
|
||
|
||
- [Install and first start](first-start.md)
|
||
- [Shell and localization](shell-and-language.md)
|
||
- [Workspace operations](../operations/workspaces.md)
|
||
- `deploy/secrets/README.md` (runtime secrets)
|