471 lines
24 KiB
HTML
471 lines
24 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
|
||
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
|
||
<link rel="canonical" href="https://git.tylconsulting.it/thothii-docs/install/standalone-manual-it/">
|
||
<link rel="shortcut icon" href="../../img/favicon.ico">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" />
|
||
<title>Mac, Windows, Linux — Italiano - ThothII Docs</title>
|
||
<link href="../../css/bootstrap-3.3.7.min.css" rel="stylesheet">
|
||
<link href="../../css/font-awesome-4.7.0.css" rel="stylesheet">
|
||
<link href="../../css/base.css" rel="stylesheet">
|
||
<link rel="stylesheet" href="../../css/highlight.css">
|
||
<link href="../../stylesheets/extra.css" rel="stylesheet">
|
||
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
|
||
<!--[if lt IE 9]>
|
||
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
|
||
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
|
||
<![endif]-->
|
||
|
||
<script src="../../js/jquery-3.2.1.min.js"></script>
|
||
<script src="../../js/bootstrap-3.3.7.min.js"></script>
|
||
<script src="../../js/highlight.pack.js"></script>
|
||
|
||
<base target="_top">
|
||
<script>
|
||
var base_url = '../..';
|
||
var is_top_frame = false;
|
||
|
||
var pageToc = [
|
||
{title: "Installazione manuale standalone", url: "#_top", children: [
|
||
{title: "Matrice di verifica", url: "#matrice-di-verifica" },
|
||
{title: "Cosa serve prima di iniziare", url: "#cosa-serve-prima-di-iniziare" },
|
||
{title: "1. Clonare una revisione del progetto", url: "#1-clonare-una-revisione-del-progetto" },
|
||
{title: "2. Verificare i prerequisiti e installare il comando operatore", url: "#2-verificare-i-prerequisiti-e-installare-il-comando-operatore" },
|
||
{title: "3. Configurare e avviare l\u2019installazione locale", url: "#3-configurare-e-avviare-linstallazione-locale" },
|
||
{title: "4. Verificare l\u2019installazione", url: "#4-verificare-linstallazione" },
|
||
{title: "Ciclo di vita quotidiano", url: "#ciclo-di-vita-quotidiano" },
|
||
{title: "Diagnosi rapida", url: "#diagnosi-rapida" },
|
||
{title: "Checklist di accettazione", url: "#checklist-di-accettazione" },
|
||
{title: "Fuori perimetro di questa release", url: "#fuori-perimetro-di-questa-release" },
|
||
{title: "Documenti collegati", url: "#documenti-collegati" },
|
||
]},
|
||
];
|
||
|
||
</script>
|
||
<script src="../../js/base.js"></script>
|
||
<script src="../../javascripts/layout-init.js"></script>
|
||
</head>
|
||
|
||
<body>
|
||
<script>
|
||
if (is_top_frame) { $('body').addClass('wm-top-page'); }
|
||
</script>
|
||
|
||
|
||
|
||
<div class="container-fluid wm-page-content">
|
||
<a name="_top"></a>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
|
||
|
||
<div class="wm-article-nav pull-right">
|
||
<a href="../standalone-manual-en/" class="btn btn-xs btn-default pull-right">
|
||
Next
|
||
<i class="fa fa-chevron-right" aria-hidden="true"></i>
|
||
</a>
|
||
<a href="../standalone-manual-en/" class="btn btn-xs btn-link">
|
||
Mac, Windows, Linux — English
|
||
</a>
|
||
</div>
|
||
|
||
<div class="wm-article-nav">
|
||
<a href="../first-start/" class="btn btn-xs btn-default pull-left">
|
||
<i class="fa fa-chevron-left" aria-hidden="true"></i>
|
||
Previous</a><a href="../first-start/" class="btn btn-xs btn-link">
|
||
Start here
|
||
</a>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
<h1 id="installazione-manuale-standalone">Installazione manuale standalone<a class="headerlink" href="#installazione-manuale-standalone" title="Permanent link">¶</a></h1>
|
||
<p><a href="../standalone-manual-en/">English version</a></p>
|
||
<p>Questa è la procedura di prova per predisporre THothII come applicazione autonoma in modalità
|
||
<code>full</code> su macOS, Windows e Linux.</p>
|
||
<p>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.</p>
|
||
<p>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.</p>
|
||
<h2 id="matrice-di-verifica">Matrice di verifica<a class="headerlink" href="#matrice-di-verifica" title="Permanent link">¶</a></h2>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Sistema</th>
|
||
<th>Terminale raccomandato</th>
|
||
<th>Runtime</th>
|
||
<th>Architettura della prova</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>macOS supportato dalla versione Docker Desktop installata</td>
|
||
<td>Bash nel Terminale</td>
|
||
<td>Docker Desktop</td>
|
||
<td>Apple Silicon (<code>arm64</code>)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Windows 11</td>
|
||
<td>Ubuntu dentro WSL2</td>
|
||
<td>Docker Desktop con integrazione WSL2</td>
|
||
<td>x64 (<code>amd64</code>)</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Linux Ubuntu 22.04 o 24.04</td>
|
||
<td>Bash</td>
|
||
<td>Docker Engine + Compose v2</td>
|
||
<td>x64 (<code>amd64</code>)</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Intel macOS non fa parte della prima campagna di verifica. ARM Linux può essere provato quando il
|
||
runtime Docker della macchina restituisce <code>arm64</code>, ma non è un requisito della matrice minima.</p>
|
||
<p>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.</p>
|
||
<h2 id="cosa-serve-prima-di-iniziare">Cosa serve prima di iniziare<a class="headerlink" href="#cosa-serve-prima-di-iniziare" title="Permanent link">¶</a></h2>
|
||
<p>Servono:</p>
|
||
<ul>
|
||
<li>accesso al repository Gitea di THothII e al repository Git dei workspace;</li>
|
||
<li>Git;</li>
|
||
<li>Docker Desktop su macOS e Windows, oppure Docker Engine con il plugin Compose v2 su Linux;</li>
|
||
<li>Bash, <code>curl</code>, OpenSSL e <code>shasum</code> (su Ubuntu, pacchetto <code>libdigest-sha-perl</code>);</li>
|
||
<li>spazio disco sufficiente per compilare le immagini e scaricare il modello di embedding;</li>
|
||
<li>gli endpoint DWH e LLM, più le credenziali che l’installazione deve usare.</li>
|
||
</ul>
|
||
<p>Su Linux l’utente corrente deve poter eseguire Docker. Se il sistema richiede <code>sudo</code>, aggiungere
|
||
l’utente al gruppo Docker secondo la policy locale e aprire una nuova sessione prima di continuare.</p>
|
||
<p>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 <code>~/src</code>, e non sotto <code>/mnt/c</code>: si evitano rallentamenti e problemi di permessi o
|
||
line ending. Non è necessario installare Pi sull’host.</p>
|
||
<p>Verificare il runtime prima del clone o subito dopo:</p>
|
||
<pre class="highlight"><code class="language-sh">docker version
|
||
docker compose version
|
||
docker version --format '{{.Server.Arch}}'</code></pre>
|
||
<p>L’ultima istruzione deve restituire <code>amd64</code>, <code>x86_64</code>, <code>arm64</code> o <code>aarch64</code>.</p>
|
||
<h2 id="1-clonare-una-revisione-del-progetto">1. Clonare una revisione del progetto<a class="headerlink" href="#1-clonare-una-revisione-del-progetto" title="Permanent link">¶</a></h2>
|
||
<p>Usare il repository di progetto su Gitea:</p>
|
||
<pre class="highlight"><code class="language-sh">mkdir -p "$HOME/src"
|
||
cd "$HOME/src"
|
||
git clone https://git.tylconsulting.it/mptyl/ThothII.git
|
||
cd ThothII
|
||
git rev-parse --short HEAD</code></pre>
|
||
<p>Per un clone SSH usare, se la chiave è già autorizzata su Gitea:</p>
|
||
<pre class="highlight"><code class="language-sh">git clone git@git.tylconsulting.it:mptyl/ThothII.git</code></pre>
|
||
<p>Per una prova ripetibile annotare l’hash stampato da <code>git rev-parse</code>. In una campagna successiva
|
||
usare la revisione/tag approvata dal maintainer invece di seguire implicitamente una <code>main</code> che
|
||
può cambiare.</p>
|
||
<h2 id="2-verificare-i-prerequisiti-e-installare-il-comando-operatore">2. Verificare i prerequisiti e installare il comando operatore<a class="headerlink" href="#2-verificare-i-prerequisiti-e-installare-il-comando-operatore" title="Permanent link">¶</a></h2>
|
||
<p>Dal root del clone:</p>
|
||
<pre class="highlight"><code class="language-sh">bash scripts/check-standalone-prerequisites.sh
|
||
export PATH="$HOME/.local/bin:$PATH"
|
||
THT_INSTALL_DIRECTORY="$HOME/.local/bin" bash scripts/install-tht.sh
|
||
tht version</code></pre>
|
||
<p><code>install-tht.sh</code> è un bootstrap del solo comando operatore nativo <code>tht</code>; 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 <code>$HOME/.local/bin</code> al PATH della
|
||
shell anche per i terminali successivi. Un <code>tht</code> già presente in quella directory viene aggiornato.</p>
|
||
<p>Su Windows, eseguire questi comandi dentro WSL2. Il binario <code>tht</code> installato è quello Linux di WSL2;
|
||
il runtime dell’applicazione rimane Docker Desktop. Non usare <code>scripts/install-tht.ps1</code> come percorso
|
||
principale di questa prova.</p>
|
||
<h2 id="3-configurare-e-avviare-linstallazione-locale">3. Configurare e avviare l’installazione locale<a class="headerlink" href="#3-configurare-e-avviare-linstallazione-locale" title="Permanent link">¶</a></h2>
|
||
<p>Eseguire i blocchi successivi nella stessa sessione Bash dal root fisico del clone (<code>pwd -P</code>).
|
||
Creare prima le due password distinte del catalogo, conservando eventuali file già esistenti:</p>
|
||
<pre class="highlight"><code class="language-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"</code></pre>
|
||
<p>Non rigenerare le password di un catalogo già inizializzato. Configurare senza avviare i servizi:</p>
|
||
<pre class="highlight"><code class="language-sh">tht setup --profile local --shell-mode full --shell-default-locale en --configure-only</code></pre>
|
||
<p>Rispondere ai prompt nel seguente modo:</p>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Prompt</th>
|
||
<th>Valore o regola</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>Installation ID</td>
|
||
<td><code>local</code>, salvo necessità di più installazioni nello stesso clone</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Deployment profile</td>
|
||
<td><code>local</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>DWH API endpoint</td>
|
||
<td>URL <code>http(s)</code> senza user, password, query o fragment; può restare vuoto per il solo smoke test</td>
|
||
</tr>
|
||
<tr>
|
||
<td>LLM API endpoint</td>
|
||
<td>URL <code>http(s)</code> senza credenziali; può restare vuoto per il solo smoke test</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Workspace repository URL</td>
|
||
<td>URL del repository dei workspace, non il clone sorgente di THothII</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Workspace branch</td>
|
||
<td>normalmente <code>main</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>Workspace access</td>
|
||
<td><code>ssh</code> se si usa una chiave deploy; altrimenti <code>https</code> con credential file protetto</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Percorsi dei file</td>
|
||
<td>accettare i percorsi predefiniti sotto <code>deploy/local/secrets/</code> nella prima prova</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Secret templates</td>
|
||
<td>rispondere <code>yes</code> quando i file protetti non esistono ancora</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Autenticazione</td>
|
||
<td>configurare il login locale richiesto dall’installazione; non inserire password in una riga di comando</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>La configurazione generata è locale e ignorata da Git:</p>
|
||
<pre class="highlight"><code class="language-text">deploy/local/thothii-installation.yaml
|
||
deploy/local/operator.env
|
||
deploy/local/auth/
|
||
deploy/local/secrets/</code></pre>
|
||
<p>Modificare i segreti solo nei file locali protetti; non committarli. Il file <code>deploy/env/local.env.example</code> è un riferimento
|
||
tracciato; il percorso generato da <code>tht setup</code>, <code>deploy/local/operator.env</code>, è quello da usare per
|
||
questa installazione.</p>
|
||
<h3 id="completare-i-file-protetti">Completare i file protetti<a class="headerlink" href="#completare-i-file-protetti" title="Permanent link">¶</a></h3>
|
||
<p>Se il setup ha creato template vuoti, inserire i valori con un editor locale:</p>
|
||
<pre class="highlight"><code class="language-sh">chmod 600 deploy/local/secrets/*
|
||
"${EDITOR:-vi}" deploy/local/secrets/thothii.secrets</code></pre>
|
||
<p>Il bundle deve contenere solo righe <code>KEY=VALUE</code> per le credenziali effettivamente usate dal
|
||
<code>modelCatalog</code>. I nomi ammessi e il confine delle credenziali sono descritti nel file locale
|
||
<code>deploy/secrets/README.md</code>. Non mettere token nelle URL, nel
|
||
descriptor YAML, nel repository Git o nei comandi copiati nella shell.</p>
|
||
<p>Per accesso workspace SSH, predisporre anche la chiave privata e il file <code>known_hosts</code> indicati dal
|
||
setup. Per accesso HTTPS, predisporre il credential file Git e l’eventuale CA. Entrambi devono
|
||
restare protetti e fuori dal controllo versione.</p>
|
||
<p>Prima dell'avvio completare anche questi passaggi:</p>
|
||
<ol>
|
||
<li>Aggiungere <code>THT_CATALOG_RUNTIME_PASSWORD_SOURCE</code> e <code>THT_CATALOG_MIGRATOR_PASSWORD_SOURCE</code> a
|
||
<code>deploy/local/operator.env</code>, con gli stessi percorsi assoluti esportati sopra. Il setup non salva
|
||
queste due variabili. Inserire i percorsi, non le password.</li>
|
||
<li>Sostituire il <code>modelCatalog</code> generico nel descriptor con la configurazione provider/modelli
|
||
approvata. I default generati non replicano il Mac esistente. Vedere <a href="../../general/pi-configuration/">configurazione Pi/modelli</a>
|
||
e l'esempio locale <code>deploy/psd/thothii-installation.yaml.example</code>.</li>
|
||
<li>Inserire in <code>thothii.secrets</code> le chiavi referenziate da <code>authentication.apiKeyEnv</code>. I provider
|
||
<code>pi_auth</code> richiedono credenziali valide nel file <code>PI_AUTH_FILE</code>; il template <code>{}</code> non autentica.</li>
|
||
<li>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.</li>
|
||
</ol>
|
||
<p>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 <code>THT_GIT_ACCESS=https</code> se scelto nel setup. Il blocco usa il nuovo descriptor <code>local</code>
|
||
con il solo overlay Git; per installazioni personalizzate includere gli overlay aggiuntivi
|
||
nello stesso ordine del descriptor.</p>
|
||
<pre class="highlight"><code class="language-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</code></pre>
|
||
<p>Fermarsi se un comando fallisce. Il nome progetto coincide con l'hash usato da <code>tht</code>, preservando
|
||
l'identità dei volumi. <code>catalog-migrate</code> applica le migrazioni Catalog e Memory; <code>tht start</code> non
|
||
lo esegue automaticamente. Il primo download del modello embedding può richiedere tempo.
|
||
Usare questa sequenza legata all'installazione, non <code>run-stack.sh</code> con env/progetto diversi.</p>
|
||
<h2 id="4-verificare-linstallazione">4. Verificare l’installazione<a class="headerlink" href="#4-verificare-linstallazione" title="Permanent link">¶</a></h2>
|
||
<p>Il descriptor generato per l’ID predefinito è:</p>
|
||
<pre class="highlight"><code class="language-sh">INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
|
||
test -f "$INSTALLATION"
|
||
bash scripts/verify-standalone-install.sh "$INSTALLATION"</code></pre>
|
||
<p>Il verificatore è read-only: esegue <code>tht doctor --json</code> e <code>tht status</code>, senza ristartare lo stack,
|
||
rigenerare la configurazione o stampare il contenuto dei segreti.</p>
|
||
<h3 id="gate-a-smoke-di-piattaforma-su-tutti-e-tre-i-computer">Gate A — smoke di piattaforma, su tutti e tre i computer<a class="headerlink" href="#gate-a-smoke-di-piattaforma-su-tutti-e-tre-i-computer" title="Permanent link">¶</a></h3>
|
||
<p>Registrare per ogni macchina:</p>
|
||
<pre class="highlight"><code class="language-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"</code></pre>
|
||
<p>Il gate passa quando il clone è integro, Docker e Compose sono raggiungibili, <code>tht doctor</code> è OK,
|
||
lo stack è avviato e il frontend risponde sulla porta locale predefinita <code>http://127.0.0.1:8080</code>.
|
||
Il doctor controlla anche workspace e Pi: registrare separatamente i loro errori senza attribuire
|
||
ogni fallimento alla piattaforma. Verificare la disponibilità HTTP con:</p>
|
||
<pre class="highlight"><code class="language-sh">curl --fail --silent --show-error http://127.0.0.1:8080/health</code></pre>
|
||
<h3 id="gate-b-verifica-funzionale">Gate B — verifica funzionale<a class="headerlink" href="#gate-b-verifica-funzionale" title="Permanent link">¶</a></h3>
|
||
<p>Eseguire almeno su una macchina con endpoint e credenziali disponibili:</p>
|
||
<p>Seguire prima <a href="../../operations/workspaces/">Workspace operations</a> 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.</p>
|
||
<ol>
|
||
<li>aprire <code>http://127.0.0.1:8080</code>;</li>
|
||
<li>autenticarsi con l’account locale configurato;</li>
|
||
<li>verificare che il workspace configurato sia leggibile;</li>
|
||
<li>avviare una domanda reale e completare i gate di revisione fino alla SQL finale;</li>
|
||
<li>fermare e riavviare l’installazione, poi ripetere <code>verify-standalone-install.sh</code>.</li>
|
||
</ol>
|
||
<p>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.</p>
|
||
<h2 id="ciclo-di-vita-quotidiano">Ciclo di vita quotidiano<a class="headerlink" href="#ciclo-di-vita-quotidiano" title="Permanent link">¶</a></h2>
|
||
<p>Usare il descriptor esplicito quando più installazioni possono essere scoperte:</p>
|
||
<pre class="highlight"><code class="language-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</code></pre>
|
||
<p><code>start --build</code> è necessario dopo una modifica al codice o per ricostruire le immagini dal clone
|
||
corrente. <code>stop</code> conserva volumi, sessioni, catalogo, stato Pi, dati Qdrant e modello embedding.
|
||
Non usare <code>docker compose down --volumes</code> 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.</p>
|
||
<h2 id="diagnosi-rapida">Diagnosi rapida<a class="headerlink" href="#diagnosi-rapida" title="Permanent link">¶</a></h2>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Sintomo</th>
|
||
<th>Controllo</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>Docker Engine is not reachable</code></td>
|
||
<td>avviare Docker Desktop oppure il servizio Docker e ripetere <code>docker info</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>Windows vede Docker ma Bash fallisce</td>
|
||
<td>eseguire la guida dentro Ubuntu WSL2 e abilitare l’integrazione della distribuzione in Docker Desktop</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>tht: command not found</code></td>
|
||
<td>aprire una nuova shell e verificare <code>command -v tht</code>; se necessario ripetere il bootstrap</td>
|
||
</tr>
|
||
<tr>
|
||
<td>line ending o script non eseguibile</td>
|
||
<td>usare un clone nel filesystem WSL2/Linux e rieseguire <code>bash scripts/...</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>architettura non supportata</td>
|
||
<td>verificare <code>docker version --format '{{.Server.Arch}}'</code>; la prova richiede <code>amd64</code> o <code>arm64</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td>descriptor o env file mancanti</td>
|
||
<td>usare il percorso <code>deploy/local/...</code> generato da <code>tht setup</code>, non un file copiato casualmente</td>
|
||
</tr>
|
||
<tr>
|
||
<td>stack sano ma workflow fallisce</td>
|
||
<td>controllare separatamente URL, credential bundle, workspace Git e autenticazione</td>
|
||
</tr>
|
||
<tr>
|
||
<td>dati apparentemente persi</td>
|
||
<td>verificare che non sia stato usato <code>down --volumes</code>; <code>stop</code> non rimuove i volumi</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<h2 id="checklist-di-accettazione">Checklist di accettazione<a class="headerlink" href="#checklist-di-accettazione" title="Permanent link">¶</a></h2>
|
||
<ul>
|
||
<li>[ ] Il clone proviene dal repository Gitea atteso e la revisione è stata annotata.</li>
|
||
<li>[ ] Docker Desktop/Engine e Compose v2 sono disponibili.</li>
|
||
<li>[ ] Il runtime restituisce un’architettura ammessa.</li>
|
||
<li>[ ] <code>tht</code> è stato costruito dal repository e risponde a <code>tht version</code>.</li>
|
||
<li>[ ] Il setup usa <code>profile: local</code>, <code>shell.mode: full</code> e <code>shell.defaultLocale: en</code>.</li>
|
||
<li>[ ] Descriptor, <code>operator.env</code>, autenticazione e segreti sono presenti solo in <code>deploy/local/</code>.</li>
|
||
<li>[ ] Nessun segreto compare in Git, URL, YAML pubblico o comandi registrati.</li>
|
||
<li>[ ] Gate A superato su macOS Apple Silicon, Windows WSL2/x64 e Linux x64.</li>
|
||
<li>[ ] Gate B eseguito almeno su una macchina con DWH e LLM disponibili.</li>
|
||
<li>[ ] Stop/start e verifica finale completati senza cancellare i volumi.</li>
|
||
</ul>
|
||
<h2 id="fuori-perimetro-di-questa-release">Fuori perimetro di questa release<a class="headerlink" href="#fuori-perimetro-di-questa-release" title="Permanent link">¶</a></h2>
|
||
<p>Restano attività successive:</p>
|
||
<ul>
|
||
<li>pubblicare immagini pre-costruite su Docker Hub;</li>
|
||
<li>ridurre ulteriormente i prompt tramite una configurazione non interattiva dedicata;</li>
|
||
<li>creare pacchetti DMG, MSI/EXE, AppImage o altri installer nativi;</li>
|
||
<li>fornire un runtime offline o un DWH/LLM locale incluso nell’applicazione.</li>
|
||
</ul>
|
||
<h2 id="documenti-collegati">Documenti collegati<a class="headerlink" href="#documenti-collegati" title="Permanent link">¶</a></h2>
|
||
<ul>
|
||
<li><a href="../first-start/">Install and first start</a></li>
|
||
<li><a href="../shell-and-language/">Shell and localization</a></li>
|
||
<li><a href="../../operations/workspaces/">Workspace operations</a></li>
|
||
<li><code>deploy/secrets/README.md</code> (runtime secrets)</li>
|
||
</ul>
|
||
|
||
<br>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
|
||
|
||
<div class="wm-article-nav pull-right">
|
||
<a href="../standalone-manual-en/" class="btn btn-xs btn-default pull-right">
|
||
Next
|
||
<i class="fa fa-chevron-right" aria-hidden="true"></i>
|
||
</a>
|
||
<a href="../standalone-manual-en/" class="btn btn-xs btn-link">
|
||
Mac, Windows, Linux — English
|
||
</a>
|
||
</div>
|
||
|
||
<div class="wm-article-nav">
|
||
<a href="../first-start/" class="btn btn-xs btn-default pull-left">
|
||
<i class="fa fa-chevron-left" aria-hidden="true"></i>
|
||
Previous</a><a href="../first-start/" class="btn btn-xs btn-link">
|
||
Start here
|
||
</a>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
<br>
|
||
</div>
|
||
|
||
<footer class="container-fluid wm-page-content">
|
||
<p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a> using <a href="https://github.com/gristlabs/mkdocs-windmill">Windmill</a> theme by Grist Labs.</p>
|
||
</footer>
|
||
|
||
</body>
|
||
</html> |