ThothII/docs/plans/2026-09-14-manual-standalone-installation.md

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.

Aggiornamento: il PRD del 27 settembre rende le immagini precompilate su Docker Hub il percorso ordinario e include la loro pubblicazione nel progetto. Il percorso con build da sorgente documentato qui resta un'alternativa; il precedente rinvio di Docker Hub è superato. La revisione del 28 settembre dello stesso PRD sostituisce inoltre il setup interattivo con preparazione dei documenti, verifiche ripetibili ed esecuzione senza richiesta di parametri.

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

1. Installare Git, Docker Desktop oppure Docker Engine + Compose v2 e Bash.
2. Su Windows, predisporre WSL2 Ubuntu e abilitarne l’integrazione in Docker Desktop.
3. Clonare https://git.tylconsulting.it/mptyl/ThothII.git e annotare la revisione.
4. Eseguire scripts/check-standalone-prerequisites.sh.
5. Eseguire scripts/install-tht.sh e verificare tht version.
6. Preparare le due password catalogo ed eseguire tht setup --profile local --shell-mode full --shell-default-locale en --configure-only.
7. 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).
8. Eseguire scripts/verify-standalone-install.sh passando il descriptor generato.
9. 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.