docs: publish bilingual manual standalone installation guides

2026-09-15 10:06:28 +02:00
parent 49333a2d35
commit 84804be9f8
12 changed files with 869 additions and 1 deletions
@@ -0,0 +1,99 @@
+# 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.