Piano per l’installazione manuale standalone

Stato: design concordato con grill-with-docs il 2026-09-14. Questo worktree definisce e rende verificabile il percorso manuale; non introduce pacchetti nativi.

Obiettivo

Permettere di predisporre una copia di THothII su macOS, Windows e Linux partendo dal clone del repository Gitea, con una configurazione locale breve e una sequenza di comandi espliciti da terminale.

“Standalone” indica una Full Thoth Shell con servizi applicativi e semantici locali eseguiti da Docker. DWH e provider LLM restano configurazioni esterne dell’installazione. Non si promette un runtime offline.

Decisioni concordate

Decisione	Scelta
Distribuzione	clone del repository Gitea
Esperienza di installazione	comandi manuali, senza installer grafico, launcher o wrapper nativo
Runtime applicativo	Docker Compose del repository
Bootstrap host	`scripts/install-tht.sh` installa soltanto il comando operatore `tht`
Configurazione	setup locale interattivo, con percorsi predefiniti e file protetti separati
Modalità shell	`full`, locale, con `defaultLocale: en`
Windows	Ubuntu in WSL2 con integrazione Docker Desktop
Architetture iniziali	macOS Apple Silicon, Windows x64, Linux x64
Immagini pre-costruite	Docker Hub in uno step successivo
Verifica	Gate A di piattaforma su tre host; Gate B funzionale su almeno un host
Documentazione	due guide sincronizzate, italiano e inglese

Sequenza operativa canonica

Installare Git, Docker Desktop oppure Docker Engine + Compose v2 e Bash.
Su Windows, predisporre WSL2 Ubuntu e abilitarne l’integrazione in Docker Desktop.
Clonare https://git.tylconsulting.it/mptyl/ThothII.git e annotare la revisione.
Eseguire scripts/check-standalone-prerequisites.sh.
Eseguire scripts/install-tht.sh e verificare tht version.
Preparare le due password catalogo ed eseguire tht setup --profile local --shell-mode full --shell-default-locale en --configure-only.
Completare file protetti, percorsi password in operator.env e catalogo modelli; generare le proiezioni, costruire le immagini, avviare catalog-db, eseguire catalog-migrate e tht start sullo stesso progetto Compose (sequenza completa nelle due guide).
Eseguire scripts/verify-standalone-install.sh passando il descriptor generato.
Registrare separatamente il risultato del Gate A e del Gate B.

tht setup genera deploy/local/thothii-installation.yaml e deploy/local/operator.env, prepara le proiezioni runtime e valida Compose; --configure-only rimanda build e avvio fino al completamento della configurazione e della migrazione. Il file tracciato deploy/env/local.env.example resta un riferimento; non è il descriptor attivo della procedura generata.

Contratti di sicurezza

I segreti non entrano nel clone, nel descriptor YAML, nelle URL, nei log o negli argomenti della shell.
I file in deploy/local/ sono ignorati da Git e restano sotto il controllo dell’operatore.
Il bundle thothii.secrets usa righe KEY=VALUE e contiene solo le credenziali richieste dai provider selezionati.
L’accesso Git del workspace usa un file credential protetto oppure una chiave SSH e known_hosts; il clone sorgente e il repository workspace restano distinti.
stop, start e doctor sono operazioni di lifecycle; down --volumes è distruttivo e non fa parte della prova normale.

Matrice di accettazione

Gate	Host	Esito richiesto
A	macOS Apple Silicon	clone, Docker/Compose, build, setup, doctor e frontend locali OK
A	Windows 11 x64 + WSL2	stessi controlli eseguiti dalla shell Ubuntu WSL2
A	Ubuntu Linux x64	stessi controlli con Docker Engine + Compose v2
B	almeno uno dei tre host	login, workspace leggibile, domanda reale fino alla SQL finale, stop/start OK

Un errore del DWH, del provider LLM, del repository workspace o delle credenziali viene registrato come errore funzionale/configurativo distinto dal risultato di portabilità Docker.

Artefatti del worktree

docs/install/standalone-manual-it.md: procedura italiana utilizzabile durante l’installazione;
docs/install/standalone-manual-en.md: versione inglese sincronizzata;
scripts/check-standalone-prerequisites.sh: controllo read-only dell’host;
scripts/verify-standalone-install.sh: controllo read-only dell’installazione avviata;
aggiornamento di navigazione e contratto documentale;
questo piano come riferimento per il successivo lavoro di packaging.

Evoluzioni escluse

Non fanno parte di questa fase DMG, MSI/EXE, AppImage, wrapper nativi, installazione automatica di Docker, immagini Docker Hub, configurazione non interattiva completa, DWH locale o LLM locale.

La prossima evoluzione consigliata è pubblicare immagini versionate e ripetere la stessa matrice senza build dal sorgente. Solo dopo una prova riuscita sui tre host sarà opportuno valutare una configurazione ridotta e, separatamente, eventuali pacchetti nativi.

Revisione per pubblicazione — 2026-09-15

Le guide separano configurazione e avvio, includono password e migrazioni Catalog/Memory, richiedono di completare il catalogo modelli e distinguono la verifica del doctor dalle dipendenze esterne. Le directory di autenticazione locali sono escluse da Git. Le prove complete da clone sui tre sistemi restano pendenti; il controllo documentale non le sostituisce.

5.4 KiB Raw Blame History Unescape Escape