Installazione manuale standalone

English version

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:

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:

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:

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:

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:

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:

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:

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:

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:

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 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.

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 è:

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:

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:

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 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:

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

Fuori perimetro di questa release

Restano attività successive:

Documenti collegati