100 lines
5.4 KiB
Markdown
100 lines
5.4 KiB
Markdown
# 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.
|