# 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

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.