mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

wip: guided standalone installation and workspace checks

Browse Source
This commit is contained in:
Codex
2026-09-26 16:41:15 +02:00
parent 0d2e573e0d
commit 67ee52624c
15 changed files with 902 additions and 560 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/install/standalone-manual-it.md
+184 -251
View File
@@ -1,329 +1,262 @@
# Installazione manuale standalone
# Installazione standalone guidata
[English version](standalone-manual-en.md)
Questa è la procedura di prova per predisporre THothII come applicazione autonoma in modalità
`full` su macOS, Windows e Linux.
Questa è la procedura per installare THothII da zero. THothII riceve una domanda in linguaggio
naturale, interroga in sola lettura un database aziendale e accompagna l’utente nella revisione
della SQL risultante. Il core, il catalogo PostgreSQL, Qdrant, il servizio di embedding e Pi vengono
eseguiti in Docker; sul computer non servono Node.js, Python o Pi.
In questo documento “autonoma” significa che l’utente non deve installare Node.js, Python o Pi
sull'host: i servizi applicativi e i servizi semantici
locali vengono eseguiti con Docker. DWH e provider LLM restano endpoint esterni configurati
dall’installazione; questa procedura non è un pacchetto offline.
## Prima di iniziare: i due repository
Il percorso non usa installer grafici, launcher nativi o immagini Docker Hub. Si parte da un clone
Gitea e si usano comandi espliciti da terminale. La pubblicazione di immagini pre-costruite è una
fase successiva.
Servono due repository distinti:
## Matrice di verifica
1. il repository dell’applicazione, che l’utente clona:
https://git.tylconsulting.it/mptyl/ThothII.git;
2. il repository dei workspace, indicato dal curatore/installatore. Non è il repository di
THothII e non va clonato manualmente nella directory dell’applicazione.
| Sistema | Terminale raccomandato | Runtime | Architettura della prova |
| --- | --- | --- | --- |
| macOS supportato dalla versione Docker Desktop installata | Bash nel Terminale | Docker Desktop | Apple Silicon (`arm64`) |
| Windows 11 | Ubuntu dentro WSL2 | Docker Desktop con integrazione WSL2 | x64 (`amd64`) |
| Linux Ubuntu 22.04 o 24.04 | Bash | Docker Engine + Compose v2 | x64 (`amd64`) |
Il repository workspace contiene il catalogo e una directory per ogni workspace, normalmente:
Intel macOS non fa parte della prima campagna di verifica. ARM Linux può essere provato quando il
runtime Docker della macchina restituisce `arm64`, ma non è un requisito della matrice minima.
~~~
thoth-workspaces.yaml
<workspace-id>/workspace.yaml
<workspace-id>/evidence/** # se il workspace dichiara Evidence
~~~
Le verifiche documentali e dei prerequisiti Mac sono passate. Le installazioni complete da zero
sui tre sistemi restano da eseguire: la matrice indica le prove previste, non una certificazione.
Il file workspace.yaml descrive identità, lingua e, opzionalmente, la sorgente Evidence. Per scelta
architetturale non contiene password del database. L’identità del database, il trasporto
(PostgreSQL, REST o tunnel), username, password, token e certificati sono configurazione locale
dell’installazione, conservata cifrata dal Catalog. Questo evita di committare credenziali nel
repository workspace.
## Cosa serve prima di iniziare
## 0. Prerequisiti della macchina
Servono:
### Windows
- accesso al repository Gitea di THothII e al repository Git dei workspace;
- Git;
- Docker Desktop su macOS e Windows, oppure Docker Engine con il plugin Compose v2 su Linux;
- Bash, `curl`, OpenSSL e `shasum` (su Ubuntu, pacchetto `libdigest-sha-perl`);
- spazio disco sufficiente per compilare le immagini e scaricare il modello di embedding;
- gli endpoint DWH e LLM, più le credenziali che l’installazione deve usare.
- Windows 10/11 con Docker Desktop avviato e backend WSL2 abilitato.
- Ubuntu in WSL2, con integrazione Docker Desktop abilitata per quella distribuzione.
- Git, Bash, curl, OpenSSL e shasum nella distribuzione WSL2.
- Non installare Node.js, Python o Pi sull’host per questa procedura.
Su Linux l’utente corrente deve poter eseguire Docker. Se il sistema richiede `sudo`, aggiungere
l’utente al gruppo Docker secondo la policy locale e aprire una nuova sessione prima di continuare.
In PowerShell, se WSL2 non esiste ancora, usare la procedura aziendale oppure:
Su Windows usare Ubuntu in WSL2 per tutti i comandi di questa guida. In Docker Desktop attivare
l’integrazione WSL2 per quella distribuzione. Clonare il progetto nel filesystem Linux di WSL2,
per esempio sotto `~/src`, e non sotto `/mnt/c`: si evitano rallentamenti e problemi di permessi o
line ending. Non è necessario installare Pi sull’host.
~~~
wsl --install -d Ubuntu
~~~
Verificare il runtime prima del clone o subito dopo:
Eseguire poi tutti i comandi dentro Ubuntu WSL2, in una directory Linux come $HOME/src, non sotto
/mnt/c. Il percorso nativo scripts/install-tht.ps1 esiste per scenari PowerShell avanzati; per la
prova riproducibile usare WSL2.
```sh
docker version
### macOS
- Docker Desktop installato, avviato e con alcuni GB liberi per immagini e modello di embedding.
- Git, Bash, curl, OpenSSL e shasum.
- Sono supportati Mac Intel e Apple Silicon se Docker Desktop supporta l’architettura restituita
dal Docker server.
- Non installare Node.js, Python o Pi sull’host per questa procedura.
### Linux, incluso Omarchy
- Git, Bash, curl, OpenSSL e shasum.
- Docker Engine e il plugin Docker Compose v2. Su Omarchy verificare prima:
~~~
command -v docker
docker compose version
docker info
~~~
Se Docker manca, installare Docker e Compose con il gestore pacchetti/procedura approvata dalla
distribuzione, poi avviare il servizio. Su una distribuzione Arch-like il percorso tipico è:
~~~
sudo pacman -S docker docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
~~~
Dopo l’aggiunta al gruppo aprire una nuova sessione e ripetere docker info. Non installare Node.js,
Python o Pi sull’host: sono dentro le immagini Docker.
Su tutti i sistemi il controllo finale è:
~~~
bash scripts/check-standalone-prerequisites.sh
docker version --format '{{.Server.Arch}}'
```
~~~
L’ultima istruzione deve restituire `amd64`, `x86_64`, `arm64` o `aarch64`.
L’architettura deve essere amd64, x86_64, arm64 o aarch64. Servono inoltre accesso al repository
Gitea dell’applicazione, URL/branch e credenziali del repository workspace, raggiungibilità dal
container degli endpoint DWH/LLM e le credenziali, token o certificati associati ai database.
## 1. Clonare una revisione del progetto
## 1. Cosa clonare
Usare il repository di progetto su Gitea:
Clonare solo l’applicazione:
```sh
~~~
mkdir -p "$HOME/src"
cd "$HOME/src"
git clone https://git.tylconsulting.it/mptyl/ThothII.git
cd ThothII
git rev-parse --short HEAD
```
~~~
Per un clone SSH usare, se la chiave è già autorizzata su Gitea:
Annotare la revisione. Il repository workspace verrà scaricato da tht setup --complete dentro un
volume Docker persistente, usando URL, branch e trasporto indicati durante il setup.
```sh
git clone git@git.tylconsulting.it:mptyl/ThothII.git
```
Per una prova ripetibile annotare l’hash stampato da `git rev-parse`. In una campagna successiva
usare la revisione/tag approvata dal maintainer invece di seguire implicitamente una `main` che
può cambiare.
## 2. Verificare i prerequisiti e installare il comando operatore
## 2. Installare il comando terminale
Dal root del clone:
```sh
~~~
bash scripts/check-standalone-prerequisites.sh
export PATH="$HOME/.local/bin:$PATH"
mkdir -p "$HOME/.local/bin"
THT_INSTALL_DIRECTORY="$HOME/.local/bin" bash scripts/install-tht.sh
export PATH="$HOME/.local/bin:$PATH"
tht version
```
~~~
`install-tht.sh` è un bootstrap del solo comando operatore nativo `tht`; non installa una versione
desktop di THothII. Usa il builder Docker del repository, installa il binario adatto all’ambiente
del terminale e lo installa nella directory utente. Aggiungere `$HOME/.local/bin` al PATH della
shell anche per i terminali successivi. Un `tht` già presente in quella directory viene aggiornato.
Il comando tht è l’unico componente nativo da installare. Costruisce il binario con Docker e
orchestra Compose; non è un secondo runtime dell’applicazione.
Su Windows, eseguire questi comandi dentro WSL2. Il binario `tht` installato è quello Linux di WSL2;
il runtime dell’applicazione rimane Docker Desktop. Non usare `scripts/install-tht.ps1` come percorso
principale di questa prova.
## 3. Preparare pochi segreti e avviare il setup completo
## 3. Configurare e avviare l’installazione locale
La prima esecuzione crea i placeholder protetti sotto deploy/local/secrets/ e si ferma se manca
una credenziale necessaria. Compilare i file indicati e rilanciare lo stesso comando: i file di
configurazione già compatibili vengono riutilizzati.
Eseguire i blocchi successivi nella stessa sessione Bash dal root fisico del clone (`pwd -P`).
Creare prima le due password distinte del catalogo, conservando eventuali file già esistenti:
~~~
tht setup --complete --profile local --shell-mode full --shell-default-locale en
~~~
```bash
umask 077
mkdir -p deploy/local/secrets
for name in catalog-runtime-password catalog-migrator-password; do
target="deploy/local/secrets/$name"
if [ ! -e "$target" ]; then
(set -C; openssl rand -hex 32 > "$target") || exit 1
fi
done
export THT_CATALOG_RUNTIME_PASSWORD_SOURCE="$(pwd -P)/deploy/local/secrets/catalog-runtime-password"
export THT_CATALOG_MIGRATOR_PASSWORD_SOURCE="$(pwd -P)/deploy/local/secrets/catalog-migrator-password"
```
Durante il setup servono solo le informazioni operative che il computer non può conoscere:
Non rigenerare le password di un catalogo già inizializzato. Configurare senza avviare i servizi:
```sh
tht setup --profile local --shell-mode full --shell-default-locale en --configure-only
```
Rispondere ai prompt nel seguente modo:
| Prompt | Valore o regola |
| Richiesta | Cosa inserire |
| --- | --- |
| Installation ID | `local`, salvo necessità di più installazioni nello stesso clone |
| Deployment profile | `local` |
| DWH API endpoint | URL `http(s)` senza user, password, query o fragment; può restare vuoto per il solo smoke test |
| LLM API endpoint | URL `http(s)` senza credenziali; può restare vuoto per il solo smoke test |
| Workspace repository URL | URL del repository dei workspace, non il clone sorgente di THothII |
| Workspace branch | normalmente `main` |
| Workspace access | `ssh` se si usa una chiave deploy; altrimenti `https` con credential file protetto |
| Percorsi dei file | accettare i percorsi predefiniti sotto `deploy/local/secrets/` nella prima prova |
| Secret templates | rispondere `yes` quando i file protetti non esistono ancora |
| Autenticazione | configurare il login locale richiesto dall’installazione; non inserire password in una riga di comando |
| Repository workspace | URL del repository dati/configurazione, non ThothII.git |
| Branch | normalmente main |
| Accesso | ssh con chiave e known_hosts, oppure https con credential file e CA |
| DWH/LLM URL | endpoint senza token nella URL |
| Login locale | utente e password iniziale richiesti dal prompt |
La configurazione generata è locale e ignorata da Git:
Il setup crea automaticamente le password casuali del Catalog e le scrive in operator.env come
percorsi, non come valori. Esegue docker compose config, costruisce le immagini, avvia il Catalog,
esegue catalog-migrate, avvia lo stack e importa il repository workspace. L’import attiva anche
l’Evidence dichiarata: almeno i file source presenti nel workspace vengono materializzati nel
registro locale.
```text
deploy/local/thothii-installation.yaml
deploy/local/operator.env
deploy/local/auth/
deploy/local/secrets/
```
### Il file da compilare
Modificare i segreti solo nei file locali protetti; non committarli. Il file `deploy/env/local.env.example` è un riferimento
tracciato; il percorso generato da `tht setup`, `deploy/local/operator.env`, è quello da usare per
questa installazione.
Il file principale è:
### Completare i file protetti
~~~
deploy/local/secrets/thothii.secrets
~~~
Se il setup ha creato template vuoti, inserire i valori con un editor locale:
Inserire solo righe NOME=VALORE necessarie al modelCatalog e agli adapter, per esempio una API key
LLM (DEEPSEEK_API_KEY, OPENAI_API_KEY o quella dichiarata dal catalogo) ed eventualmente
THT_DWH_API_KEY. I nomi ammessi sono documentati in deploy/secrets/README.md. Non mettere token
nelle URL, nel repository o nei comandi.
```sh
chmod 600 deploy/local/secrets/*
"${EDITOR:-vi}" deploy/local/secrets/thothii.secrets
```
Due precisazioni evitano gli errori più comuni:
Il bundle deve contenere solo righe `KEY=VALUE` per le credenziali effettivamente usate dal
`modelCatalog`. I nomi ammessi e il confine delle credenziali sono descritti nel file locale
`deploy/secrets/README.md`. Non mettere token nelle URL, nel
descriptor YAML, nel repository Git o nei comandi copiati nella shell.
- se il catalogo usa pi_auth, il token LLM va nel file Pi pi-auth.json creato dal setup; {} è solo
un placeholder e non abilita alcun modello;
- le credenziali specifiche di un database workspace (password PostgreSQL, API token REST, chiave
SSH del tunnel, known_hosts, CA) non vanno nel repository workspace: si inseriscono per workspace
in Database Management, che le conserva nel Catalog cifrato. Il workspace indica database/schema
e trasporto; l’installatore deve ottenere dal proprietario il valore corretto.
Per accesso workspace SSH, predisporre anche la chiave privata e il file `known_hosts` indicati dal
setup. Per accesso HTTPS, predisporre il credential file Git e l’eventuale CA. Entrambi devono
restare protetti e fuori dal controllo versione.
Per un repository workspace privato sono inoltre indispensabili i file Git richiesti dal trasporto:
una chiave SSH e known_hosts, oppure credential file HTTPS e CA. Sono file di trasporto, non un
secondo bundle da committare. Per ridurre i file da compilare, usare SSH con una deploy key già
autorizzata.
Prima dell'avvio completare anche questi passaggi:
## 4. Controlli automatici e test da terminale
1. Aggiungere `THT_CATALOG_RUNTIME_PASSWORD_SOURCE` e `THT_CATALOG_MIGRATOR_PASSWORD_SOURCE` a
`deploy/local/operator.env`, con gli stessi percorsi assoluti esportati sopra. Il setup non salva
queste due variabili. Inserire i percorsi, non le password.
2. Sostituire il `modelCatalog` generico nel descriptor con la configurazione provider/modelli
approvata. I default generati non replicano il Mac esistente. Vedere [configurazione Pi/modelli](../general/pi-configuration.md)
e l'esempio locale `deploy/psd/thothii-installation.yaml.example`.
3. Inserire in `thothii.secrets` le chiavi referenziate da `authentication.apiKeyEnv`. I provider
`pi_auth` richiedono credenziali valide nel file `PI_AUTH_FILE`; il template `{}` non autentica.
4. Completare i file Git del workspace. SSH richiede una chiave deploy autorizzata e known-hosts
verificato; HTTPS richiede il credential file e il bundle CA previsti dall'overlay. I template
vuoti non consentono l'accesso al repository.
Il setup verifica file, permessi, descriptor, Compose, Docker, autenticazione, servizi, Pi e
workspace. Dopo l’avvio usare questi comandi in qualunque momento:
Dopo aver modificato la configurazione generata, non rilanciare setup: rifiuta file esistenti con
contenuti diversi. Generare le proiezioni ed eseguire la migrazione esplicita indicata sotto.
Impostare `THT_GIT_ACCESS=https` se scelto nel setup. Il blocco usa il nuovo descriptor `local`
con il solo overlay Git; per installazioni personalizzate includere gli overlay aggiuntivi
nello stesso ordine del descriptor.
~~~
INSTALLATION="$PWD/deploy/local/thothii-installation.yaml"
tht --installation "$INSTALLATION" doctor --json
tht --installation "$INSTALLATION" workspace pull --json
tht --installation "$INSTALLATION" workspace test --json
~~~
```bash
INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
tht --installation "$INSTALLATION" installation generate
THT_PROJECT="thothii-$(printf '%s' "$INSTALLATION" | shasum -a 256 | cut -c 1-12)"
THT_GIT_ACCESS=ssh
compose=(
docker compose --project-name "$THT_PROJECT" --project-directory "$(pwd -P)"
--env-file "$(pwd -P)/deploy/local/operator.env"
-f compose.yaml -f deploy/compose.local.yaml
-f "deploy/compose.git-$THT_GIT_ACCESS.yaml"
-f deploy/local/generated/compose.models.yaml
)
"${compose[@]}" config --quiet
"${compose[@]}" build core frontend
"${compose[@]}" up -d catalog-db
"${compose[@]}" run --rm catalog-migrate
tht --installation "$INSTALLATION" start
```
workspace test prova, per ogni workspace attivo, il binding del database e le credenziali, Evidence,
Qdrant e il servizio embedding. Restituisce exit code diverso da zero se manca il binding del
database o una connessione non è utilizzabile. Prima di eseguirlo l’installatore deve aver
configurato il database in Database Management: il workspace repository da solo non può contenere
la password.
Fermarsi se un comando fallisce. Il nome progetto coincide con l'hash usato da `tht`, preservando
l'identità dei volumi. `catalog-migrate` applica le migrazioni Catalog e Memory; `tht start` non
lo esegue automaticamente. Il primo download del modello embedding può richiedere tempo.
Usare questa sequenza legata all'installazione, non `run-stack.sh` con env/progetto diversi.
Per una verifica generale del core, doctor --json è il test ripetibile e non distruttivo. Il test
funzionale finale deve inoltre aprire http://127.0.0.1:8080, autenticarsi e completare una domanda
reale fino alla SQL finale.
## 4. Verificare l’installazione
## Attività che può svolgere solo l’installatore
Il descriptor generato per l’ID predefinito è:
La procedura automatizza il bootstrap, non può inventare decisioni o autorizzazioni aziendali.
L’installatore deve completare e registrare:
```sh
INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
test -f "$INSTALLATION"
bash scripts/verify-standalone-install.sh "$INSTALLATION"
```
1. quali LLM sono utilizzabili, il relativo modelCatalog e le API key collegate; poi eseguire
tht pi test e tht doctor;
2. per ogni database: configurazione, test connessione, sincronizzazione dello schema e
generazione delle descrizioni;
3. consolidamento umano delle descrizioni generate;
4. generazione delle entry semantiche in Qdrant tramite workspace preprocess run;
5. generazione delle FK suggerite dal naming, come complemento alle FK lette dallo schema, revisione
umana delle proposte e caricamento delle relazioni approvate in Qdrant;
6. verifica periodica con tht doctor --json e tht workspace test --json;
7. una domanda reale completata con successo, senza errori di connessione o modello.
Il verificatore è read-only: esegue `tht doctor --json` e `tht status`, senza ristartare lo stack,
rigenerare la configurazione o stampare il contenuto dei segreti.
La configurazione è dichiarata completa solo quando tutti i punti applicabili sono stati eseguiti,
le decisioni sono state registrate e i due test terminali sono verdi. Il core è dichiarato usabile
solo dopo la domanda reale, non perché il frontend risponde a /health.
### Gate A — smoke di piattaforma, su tutti e tre i computer
## Gate A e Gate B
Registrare per ogni macchina:
### Gate A — piattaforma
```sh
~~~
uname -a
docker version --format '{{.Server.Version}} {{.Server.Arch}}'
tht version
bash scripts/check-standalone-prerequisites.sh
bash scripts/verify-standalone-install.sh "$INSTALLATION"
```
~~~
Il gate passa quando il clone è integro, Docker e Compose sono raggiungibili, `tht doctor` è OK,
lo stack è avviato e il frontend risponde sulla porta locale predefinita `http://127.0.0.1:8080`.
Il doctor controlla anche workspace e Pi: registrare separatamente i loro errori senza attribuire
ogni fallimento alla piattaforma. Verificare la disponibilità HTTP con:
### Gate B — usabilità
```sh
curl --fail --silent --show-error http://127.0.0.1:8080/health
```
### Gate B — verifica funzionale
Eseguire almeno su una macchina con endpoint e credenziali disponibili:
Seguire prima [Workspace operations](../operations/workspaces.md) per importare/preparare il
workspace e configurare Database e binding locale. Il clone sorgente non trasferisce catalogo,
segreti o sessioni del Mac. Connettere l'eventuale VPN richiesta da DWH/modelli e verificare
che i relativi nomi siano raggiungibili anche dai container.
1. aprire `http://127.0.0.1:8080`;
2. autenticarsi con l’account locale configurato;
3. verificare che il workspace configurato sia leggibile;
4. avviare una domanda reale e completare i gate di revisione fino alla SQL finale;
5. fermare e riavviare l’installazione, poi ripetere `verify-standalone-install.sh`.
Un fallimento del Gate B per DWH, provider LLM, Git workspace o credenziali non dimostra da solo un
problema di portabilità Docker: registrare separatamente l’endpoint o il componente fallito.
## Ciclo di vita quotidiano
Usare il descriptor esplicito quando più installazioni possono essere scoperte:
```sh
INSTALLATION="$PWD/deploy/local/thothii-installation.yaml"
tht --installation "$INSTALLATION" status
tht --installation "$INSTALLATION" start
tht --installation "$INSTALLATION" start --build
tht --installation "$INSTALLATION" logs
~~~
tht --installation "$INSTALLATION" doctor --json
tht --installation "$INSTALLATION" stop
```
tht --installation "$INSTALLATION" workspace test --json
curl --fail --silent --show-error http://127.0.0.1:8080/health
~~~
`start --build` è necessario dopo una modifica al codice o per ricostruire le immagini dal clone
corrente. `stop` conserva volumi, sessioni, catalogo, stato Pi, dati Qdrant e modello embedding.
Non usare `docker compose down --volumes` durante una prova normale: è un’operazione distruttiva
che cancella i dati locali.
Per aggiornamenti che richiedono migrazioni, seguire il runbook della release prima dell'avvio.
Poi eseguire una domanda reale e fermare/riavviare con tht stop e tht start. Non usare docker
compose down --volumes: cancella Catalog, sessioni, Qdrant e il modello embedding.
## Diagnosi rapida
| Sintomo | Controllo |
| Sintomo | Azione |
| --- | --- |
| `Docker Engine is not reachable` | avviare Docker Desktop oppure il servizio Docker e ripetere `docker info` |
| Windows vede Docker ma Bash fallisce | eseguire la guida dentro Ubuntu WSL2 e abilitare l’integrazione della distribuzione in Docker Desktop |
| `tht: command not found` | aprire una nuova shell e verificare `command -v tht`; se necessario ripetere il bootstrap |
| line ending o script non eseguibile | usare un clone nel filesystem WSL2/Linux e rieseguire `bash scripts/...` |
| architettura non supportata | verificare `docker version --format '{{.Server.Arch}}'`; la prova richiede `amd64` o `arm64` |
| descriptor o env file mancanti | usare il percorso `deploy/local/...` generato da `tht setup`, non un file copiato casualmente |
| stack sano ma workflow fallisce | controllare separatamente URL, credential bundle, workspace Git e autenticazione |
| dati apparentemente persi | verificare che non sia stato usato `down --volumes`; `stop` non rimuove i volumi |
## Checklist di accettazione
- [ ] Il clone proviene dal repository Gitea atteso e la revisione è stata annotata.
- [ ] Docker Desktop/Engine e Compose v2 sono disponibili.
- [ ] Il runtime restituisce un’architettura ammessa.
- [ ] `tht` è stato costruito dal repository e risponde a `tht version`.
- [ ] Il setup usa `profile: local`, `shell.mode: full` e `shell.defaultLocale: en`.
- [ ] Descriptor, `operator.env`, autenticazione e segreti sono presenti solo in `deploy/local/`.
- [ ] Nessun segreto compare in Git, URL, YAML pubblico o comandi registrati.
- [ ] Gate A superato su macOS Apple Silicon, Windows WSL2/x64 e Linux x64.
- [ ] Gate B eseguito almeno su una macchina con DWH e LLM disponibili.
- [ ] Stop/start e verifica finale completati senza cancellare i volumi.
## Fuori perimetro di questa release
Restano attività successive:
- pubblicare immagini pre-costruite su Docker Hub;
- ridurre ulteriormente i prompt tramite una configurazione non interattiva dedicata;
- creare pacchetti DMG, MSI/EXE, AppImage o altri installer nativi;
- fornire un runtime offline o un DWH/LLM locale incluso nell’applicazione.
| Docker Engine is not reachable | avviare Docker Desktop o systemctl e ripetere docker info |
| Omarchy non trova docker | installare Docker/Compose, abilitare il servizio e riaprire la sessione |
| Windows vede Docker ma Bash fallisce | usare Ubuntu WSL2 e abilitarne l’integrazione in Docker Desktop |
| pull workspace fallisce | controllare URL, branch, chiave/credential file e known_hosts dal container |
| workspace test segnala binding mancante | configurare database, token/password e CA in Database Management |
| Pi non è pronto | compilare pi-auth.json o la chiave dichiarata dal modelCatalog, poi eseguire tht pi test |
## Documenti collegati
- [Install and first start](first-start.md)
- [Shell and localization](shell-and-language.md)
- [Workspace operations](../operations/workspaces.md)
- `deploy/secrets/README.md` (runtime secrets)
- [Installazione e primo avvio](first-start.md)
- [Operazioni sui workspace](../operations/workspaces.md)
- [Database Management](../operations/database-management.md)
- [Configurazione dei modelli](../general/pi-configuration.md)
- deploy/secrets/README.md
La pubblicazione di immagini su Docker Hub e gli installer nativi DMG/MSI/AppImage restano attività
successive: questa procedura parte dal clone Gitea e non richiede immagini Docker Hub pre-pubblicate.