Publish documentation for 2f53512e4d

This commit is contained in:
Gitea Actions
2026-09-26 22:42:08 +00:00
commit cb50f5a6a4
55 changed files with 33829 additions and 0 deletions
+193
View File
@@ -0,0 +1,193 @@
<!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/authentication-local/">
<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>Local authentication - 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: "Local authentication", url: "#_top", children: [
{title: "Bootstrap", url: "#bootstrap" },
{title: "User administration", url: "#user-administration" },
{title: "Session behavior and recovery", url: "#session-behavior-and-recovery" },
{title: "Projected server installations", url: "#projected-server-installations" },
]},
];
</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="../authentication-oidc/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../authentication-oidc/" class="btn btn-xs btn-link">
OIDC authentication
</a>
</div>
<div class="wm-article-nav">
<a href="../shell-and-language/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../shell-and-language/" class="btn btn-xs btn-link">
Display mode and language
</a>
</div>
</div>
<h1 id="local-authentication">Local authentication<a class="headerlink" href="#local-authentication" title="Permanent link">&para;</a></h1>
<p>Use local mode for a standalone PC or Mac, with <code>shell.mode: full</code> and
<code>shell.defaultLocale: en</code> in the installation descriptor. Presentation and
authentication are independent: selecting full does not create accounts. Omics
embedded instead uses the <a href="../shell-and-language/">upstream guide</a>, not local users.</p>
<p>Configure local authentication through <code>tht</code>; passwords are entered at an
echo-free prompt or read from a protected <code>--password-file</code>, never from a command argument.</p>
<h2 id="bootstrap">Bootstrap<a class="headerlink" href="#bootstrap" title="Permanent link">&para;</a></h2>
<p>After the installation descriptor and protected secret bundle exist, configure the first enabled
administrator:</p>
<pre class="highlight"><code class="language-sh">tht --installation /absolute/path/thothii-installation.yaml auth configure \
--mode local --public-url http://127.0.0.1:8080 \
--admin-user &lt;operator-user&gt; --admin-display-name &lt;display-name&gt; \
--password-file /absolute/path/protected-password-file</code></pre>
<p>The password file is temporary operator input: keep it private and remove it after configuration.
The resulting <code>users.yaml</code> contains Argon2id hashes, never plaintext passwords. To use prompts,
omit the admin and password options in an interactive terminal. <code>tht setup</code> performs the same
bootstrap before it starts the stack.</p>
<p>The non-secret local <code>auth.yaml</code> has this exact shape:</p>
<pre class="highlight"><code class="language-yaml">version: 1
mode: local
publicUrl: http://127.0.0.1:8080
session:
regularTtlSeconds: 43200
regularIdleSeconds: 7200
rememberTtlSeconds: 2592000
rememberIdleSeconds: 604800
oidcTtlSeconds: 28800
local:
usersFile: users.yaml</code></pre>
<h2 id="user-administration">User administration<a class="headerlink" href="#user-administration" title="Permanent link">&para;</a></h2>
<pre class="highlight"><code class="language-sh">tht auth user list [--json]
tht auth user add &lt;username&gt; --role user|admin [--display-name &lt;name&gt;] [--password-file &lt;file&gt;]
tht auth user set-password &lt;username&gt; [--password-file &lt;file&gt;]
tht auth user enable &lt;username&gt;
tht auth user disable &lt;username&gt;
tht auth user grant &lt;username&gt; --role user|admin
tht auth user revoke &lt;username&gt; --role user|admin
tht auth user logout-all &lt;username&gt; --yes</code></pre>
<p>User commands are unavailable in OIDC mode. The last enabled administrator cannot be disabled or
demoted. Every password, role, enabled-state, and <code>logout-all</code> change increments the user’s
<code>authRevision</code>, invalidating its sessions. <code>tht auth status --json</code> is redacted and suitable for
machine use; JSON output is pristine on stdout.</p>
<h2 id="session-behavior-and-recovery">Session behavior and recovery<a class="headerlink" href="#session-behavior-and-recovery" title="Permanent link">&para;</a></h2>
<p>Full shows its own login form and, after login, the verified display name in its
header. The name menu contains Log out. This sends a CSRF-protected request to
<code>/api/auth/logout</code>, revokes the session and returns to login. Language/theme
preferences may remain in the browser; they are not credentials.</p>
<p>An ordinary login expires after 2 hours idle or 12 hours absolute. Selecting <strong>Remember me</strong> makes
the cookie persistent and changes the limits to 7 days idle or 30 days absolute. Remembered
sessions survive a browser and backend restart, but not a user revision change, configuration
revision change, logout, or restore. Restore does not include sessions or OIDC state and requires
every user to authenticate again.</p>
<p>If access is lost, use <code>tht auth user set-password</code>, <code>enable</code>, role changes, or <code>logout-all</code> as
appropriate, then log in again. Do not copy passwords, hashes, cookies, CSRF values, or secret
values into tickets, logs, or evidence.</p>
<p>Check readiness with <code>tht auth check</code>; add <code>--json</code> for the machine contract. Use
<code>tht doctor --json</code> for the aggregate installation report.</p>
<h2 id="projected-server-installations">Projected server installations<a class="headerlink" href="#projected-server-installations" title="Permanent link">&para;</a></h2>
<p>This section applies only when a Linux <code>profile: server</code> descriptor declares a runtime projection.
The canonical authentication root stays root-owned and is the only authority. The container reads
only the separate read-only runtime projection selected by <code>CURRENT</code>; it never falls back to the
canonical files or to a previous generation. Run projected mutations and repairs through the
root-operated <code>tht</code> commands, and never edit runtime files directly.</p>
<p>Mac, Windows, and local direct-file authentication remain unchanged when the projection is absent.</p>
<br>
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
<div class="wm-article-nav pull-right">
<a href="../authentication-oidc/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../authentication-oidc/" class="btn btn-xs btn-link">
OIDC authentication
</a>
</div>
<div class="wm-article-nav">
<a href="../shell-and-language/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../shell-and-language/" class="btn btn-xs btn-link">
Display mode and language
</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>
+218
View File
@@ -0,0 +1,218 @@
<!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/authentication-oidc/">
<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>OIDC authentication - 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: "Generic OIDC authentication", url: "#_top", children: [
{title: "The groups claim is mandatory", url: "#the-groups-claim-is-mandatory" },
{title: "Checks and diagnostics", url: "#checks-and-diagnostics" },
{title: "Browser login and logout", url: "#browser-login-and-logout" },
]},
];
</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="../authentik/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../authentik/" class="btn btn-xs btn-link">
Authentik
</a>
</div>
<div class="wm-article-nav">
<a href="../authentication-local/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../authentication-local/" class="btn btn-xs btn-link">
Local authentication
</a>
</div>
</div>
<h1 id="generic-oidc-authentication">Generic OIDC authentication<a class="headerlink" href="#generic-oidc-authentication" title="Permanent link">&para;</a></h1>
<p>Use this guide for <strong>ThothII's own login</strong>, normally <code>shell.mode: full</code> on an
autonomous server. It is not the integration procedure for an already logged-in
Omics user. That deployment uses <a href="../shell-and-language/">embedded/upstream</a>,
even when Omics's identity provider is Authentik.</p>
<p>OIDC mode supports a standards-based provider. The browser flow is generic: Authorization Code,
PKCE S256, state, nonce, issuer/signature/audience/expiry validation, and the fixed callback
<code>&lt;publicUrl&gt;/api/auth/oidc/callback</code>. The browser and API must use the same origin; configure the
reverse proxy to preserve that public origin and callback path.</p>
<p><code>publicUrl</code> is the public origin, without an application subpath. The current
full OIDC browser entry and callback use <code>/api/auth/oidc/login</code> and
<code>/api/auth/oidc/callback</code>; arbitrary prefixed OIDC hosting is not implemented by
selecting a different <code>backendBaseUrl</code>.</p>
<p>Configure the installation with <code>tht</code>:</p>
<pre class="highlight"><code class="language-sh">tht auth configure --mode oidc --public-url &lt;https-public-origin&gt; \
--issuer &lt;https-issuer&gt; --client-id &lt;client-id&gt; \
--authentik-base-url &lt;https-provider-origin&gt; \
--user-group 'TOT Users' --admin-group 'TOT Admin'</code></pre>
<p>The OIDC client secret is supplied through the protected secret bundle under the exact key
<code>THT_OIDC_CLIENT_SECRET</code>; it is never written into <code>auth.yaml</code>. The default scopes are exactly
<code>openid</code>, <code>profile</code>, and <code>email</code>.</p>
<p>Keep <code>AUTH_MODE</code> unset when using this file. A simultaneously mounted local/OIDC
configuration and <code>AUTH_MODE=upstream</code> is an error, not a fallback chain.</p>
<p>The non-secret OIDC configuration has this exact shape (replace angle-bracket placeholders with
operator values):</p>
<pre class="highlight"><code class="language-yaml">version: 1
mode: oidc
publicUrl: &lt;https-public-origin&gt;
session:
regularTtlSeconds: 43200
regularIdleSeconds: 7200
rememberTtlSeconds: 2592000
rememberIdleSeconds: 604800
oidcTtlSeconds: 28800
oidc:
issuer: &lt;https-issuer&gt;
clientId: &lt;client-id&gt;
clientSecretRef: THT_OIDC_CLIENT_SECRET
scopes: [openid, profile, email]
groupsClaim: groups
groupCatalog:
driver: authentik
baseUrl: &lt;https-provider-origin&gt;
apiTokenRef: THT_AUTHENTIK_API_TOKEN
authorization:
groupRoles:
TOT Users: [user]
TOT Admin: [admin]</code></pre>
<h2 id="the-groups-claim-is-mandatory">The groups claim is mandatory<a class="headerlink" href="#the-groups-claim-is-mandatory" title="Permanent link">&para;</a></h2>
<p>The ID token must contain a direct, non-empty <code>groups</code> array of strings. ThothII does not follow
distributed claims, overage links, or indirect provider expansion. Missing or malformed claims fail
closed. A browser callback exposes only HTTP 401 <code>oidc_callback_failed</code>; it never reveals whether
the claim was missing, malformed, indirect, or overage-style. The redacted diagnostic and
interactive device-flow contract uses <code>oidc_groups_claim_invalid</code> for invalid group-claim or
device-flow identity results.</p>
<p>Configured group names are exact and case-sensitive. The union of matched mappings determines the
Thoth roles. A token with no mapped group is authenticated but has no role and cannot use protected
routes. Additional provider groups are ignored silently, without an error or warning. Group
existence is separately proven by the configured catalog adapter; this is why a generic OIDC
provider may authenticate while still failing installation readiness.</p>
<h2 id="checks-and-diagnostics">Checks and diagnostics<a class="headerlink" href="#checks-and-diagnostics" title="Permanent link">&para;</a></h2>
<p>The surfaces have distinct semantics and this order is recommended:</p>
<ol>
<li>Workspace Validate performs static authentication validation without contacting the provider.</li>
<li><code>tht auth check</code> performs live, non-interactive authentication diagnosis, including discovery,
issuer/JWKS, catalog credentials, and all configured mapped groups.</li>
<li><code>tht auth check --interactive</code> repeats live diagnosis and additionally validates a device-flow
identity and its direct <code>groups</code> claim when Device Authorization is available.</li>
<li>Installation diagnostics perform aggregate live workspace and authentication validation.</li>
</ol>
<p>The live CLI forms are:</p>
<pre class="highlight"><code class="language-sh">tht auth check
tht auth check --json</code></pre>
<p>For a provider that advertises Device Authorization, <code>tht auth check --interactive</code> presents a
verification URI and one-time user code on the terminal, waits for completion, and validates a
real ID token including <code>groups</code>. It is an operator check, not a replacement for browser login.</p>
<p><code>tht doctor</code> emits this exact ordered report: <code>descriptor</code>, <code>files</code>, <code>docker</code>, <code>compose</code>,
<code>configuration</code>, <code>authentication</code>, <code>services</code>, <code>core-http</code>, <code>frontend-http</code>,
<code>workspace-registry</code>, <code>workflow</code>, <code>pi</code>. Its authentication entry is live and non-interactive.
Any authentication failure prevents activation according to the static or live scope of the
relevant diagnostic surface.</p>
<p>The complete closed diagnostic-code union and exact role-to-permission expansion are in the
<a href="https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/architecture/authentication.md">authentication architecture</a>.</p>
<h2 id="browser-login-and-logout">Browser login and logout<a class="headerlink" href="#browser-login-and-logout" title="Permanent link">&para;</a></h2>
<p>ThothII redirects the browser to the provider and creates its own opaque session
after validating the callback. An existing provider SSO session may avoid another
password prompt, but this remains a distinct ThothII login/session, unlike Omics
upstream. Full's name menu logs out of ThothII only. It does not revoke the
provider session or log out other applications, so a subsequent login can return
immediately through SSO. No provider token is placed in the UI adapter or browser
storage. See the <a href="https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/testing/authentication-manual-acceptance.md">manual acceptance matrix</a>.</p>
<br>
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
<div class="wm-article-nav pull-right">
<a href="../authentik/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../authentik/" class="btn btn-xs btn-link">
Authentik
</a>
</div>
<div class="wm-article-nav">
<a href="../authentication-local/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../authentication-local/" class="btn btn-xs btn-link">
Local authentication
</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>
+130
View File
@@ -0,0 +1,130 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta content="IE=edge" http-equiv="X-UA-Compatible"/>
<meta content="width=device-width, initial-scale=1.0" name="viewport"/>
<link href="https://git.tylconsulting.it/thothii-docs/install/authentik/" rel="canonical"/>
<link href="../../img/favicon.ico" rel="shortcut icon"/>
<meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" name="viewport"/>
<title>Authentik - 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 href="../../css/highlight.css" rel="stylesheet"/>
<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: "Authentik provider configuration", url: "#_top", children: [
{title: "OIDC provider", url: "#oidc-provider" },
{title: "Group catalog", url: "#group-catalog" },
{title: "Diagnostics", url: "#diagnostics" },
]},
];
</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 aria-label="navigation" class="row wm-article-nav-buttons" role="navigation">
<div class="wm-article-nav pull-right">
<a class="btn btn-xs btn-default pull-right" href="../../general/pi-configuration/">
Next
<i aria-hidden="true" class="fa fa-chevron-right"></i>
</a>
<a class="btn btn-xs btn-link" href="../../general/pi-configuration/">
Model configuration
</a>
</div>
<div class="wm-article-nav">
<a class="btn btn-xs btn-default pull-left" href="../authentication-oidc/">
<i aria-hidden="true" class="fa fa-chevron-left"></i>
Previous</a><a class="btn btn-xs btn-link" href="../authentication-oidc/">
OIDC authentication
</a>
</div>
</div>
<h1 id="authentik-provider-configuration">Authentik provider configuration<a class="headerlink" href="#authentik-provider-configuration" title="Permanent link"></a></h1>
<p>For <strong>full with direct OIDC</strong>, ThothII uses generic OIDC in the browser. Authentik
provides the identity provider and group catalog without adding a proprietary flow.
The provider/client/group setup below applies to that case only.</p>
<p>For <strong>embedded in Omics</strong>, retain Omics's existing Authentik authentication and
configure ThothII as upstream. Omics verifies <code>datamart_builder.access</code> and
administrator status and the proxy supplies the identity; no additional ThothII
OIDC client, login or local user is required for that path. Follow the
<a href="../shell-and-language/">portal integration guide</a>.</p>
<div class="mermaid">sequenceDiagram
participant Browser
participant ThothII
participant Authentik
Browser-&gt;&gt;ThothII: Sign in
ThothII-&gt;&gt;Authentik: Authorization Code with PKCE
Authentik--&gt;&gt;Browser: Login and consent
Browser-&gt;&gt;ThothII: Callback with code
ThothII-&gt;&gt;Authentik: Token exchange
Authentik--&gt;&gt;ThothII: Identity and groups
ThothII--&gt;&gt;Browser: Opaque session
</div>
<h2 id="oidc-provider">OIDC provider<a class="headerlink" href="#oidc-provider" title="Permanent link"></a></h2>
<ol>
<li>Create an OAuth2/OIDC application and provider.</li>
<li>Register exactly <code>PUBLIC_URL/api/auth/oidc/callback</code>.</li>
<li>Enable the <code>openid</code>, <code>profile</code>, and <code>email</code> scopes.</li>
<li>Configure a direct <code>groups</code> claim as an array of strings.</li>
</ol>
<h2 id="group-catalog">Group catalog<a class="headerlink" href="#group-catalog" title="Permanent link"></a></h2>
<p>Create a dedicated service account with read-only access to groups. Store its token in the
protected bundle as <code>THT_AUTHENTIK_API_TOKEN</code>.</p>
<p>Map the exact enterprise group names to the ThothII <code>user</code> and <code>admin</code> roles in <code>auth.yaml</code>.
Unmapped groups are ignored. A configured group that does not exist produces a closed error.</p>
<h2 id="diagnostics">Diagnostics<a class="headerlink" href="#diagnostics" title="Permanent link"></a></h2>
<p><code>tht auth check</code> checks discovery, the issuer, JWKS, catalog access, and the configured groups.
The <code>--interactive</code> option also verifies identity through device flow when the provider supports it.</p>
<p>Rotate the OIDC secret and group-catalog token separately. Neither may appear in YAML, shell
history, logs, or diagnostic output.</p>
<br/>
<div aria-label="navigation" class="row wm-article-nav-buttons" role="navigation">
<div class="wm-article-nav pull-right">
<a class="btn btn-xs btn-default pull-right" href="../../general/pi-configuration/">
Next
<i aria-hidden="true" class="fa fa-chevron-right"></i>
</a>
<a class="btn btn-xs btn-link" href="../../general/pi-configuration/">
Model configuration
</a>
</div>
<div class="wm-article-nav">
<a class="btn btn-xs btn-default pull-left" href="../authentication-oidc/">
<i aria-hidden="true" class="fa fa-chevron-left"></i>
Previous</a><a class="btn btn-xs btn-link" href="../authentication-oidc/">
OIDC authentication
</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>
<script type="module">import mermaid from "https://unpkg.com/mermaid@10.4.0/dist/mermaid.esm.min.mjs";
mermaid.initialize({});</script></body>
</html>
@@ -0,0 +1,170 @@
<!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/dwh-auth-client-enrollment/">
<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>Client enrollment - 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: "DWH REST client enrollment", url: "#_top", children: [
{title: "Delivery and storage", url: "#delivery-and-storage" },
{title: "ACME Limited configuration", url: "#acme-limited-configuration" },
{title: "Rotation and revocation", url: "#rotation-and-revocation" },
]},
];
</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="../dwh-auth-tls/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../dwh-auth-tls/" class="btn btn-xs btn-link">
TLS
</a>
</div>
<div class="wm-article-nav">
<a href="../dwh-auth-server/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../dwh-auth-server/" class="btn btn-xs btn-link">
Server
</a>
</div>
</div>
<h1 id="dwh-rest-client-enrollment">DWH REST client enrollment<a class="headerlink" href="#dwh-rest-client-enrollment" title="Permanent link">&para;</a></h1>
<p>The <code>dwh-auth</code> credential belongs to one ThothII installation and is needed only when the
workspace uses the <code>rest_api</code> transport.</p>
<table>
<thead>
<tr>
<th>Trasporto</th>
<th>Materiale richiesto</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>rest_api</code></td>
<td>URL HTTPS, <code>API_KEY_FILE</code>, eventuale <code>TLS_CA_FILE</code></td>
</tr>
<tr>
<td><code>postgres_direct</code></td>
<td>Credenziali PostgreSQL e configurazione TLS PostgreSQL</td>
</tr>
<tr>
<td><code>ssh_tunnel</code></td>
<td>Credenziali PostgreSQL e materiale SSH</td>
</tr>
</tbody>
</table>
<h2 id="delivery-and-storage">Delivery and storage<a class="headerlink" href="#delivery-and-storage" title="Permanent link">&para;</a></h2>
<p>Receive the key and CA through separate protected channels. Store the key in the installation
vault or in a regular file accessible only to the authorized account. Do not put it in Git, YAML
files, arguments, logs, or shared screens.</p>
<h2 id="acme-limited-configuration">ACME Limited configuration<a class="headerlink" href="#acme-limited-configuration" title="Permanent link">&para;</a></h2>
<p>Esempio di binding headless per il workspace <code>acme-ebikes</code>:</p>
<pre class="highlight"><code class="language-dotenv">THT_WS_ACME_EBIKES_DWH_TRANSPORT=rest_api
THT_WS_ACME_EBIKES_DWH_BASE_URL=https://dwh.acme.example/dwh/
THT_WS_ACME_EBIKES_DWH_API_KEY_FILE=/run/secrets/acme-ebikes-dwh-api-key
THT_WS_ACME_EBIKES_DWH_TLS_CA_FILE=/run/secrets/acme-ebikes-dwh-ca.pem</code></pre>
<p>The workspace suffix comes from the immutable ID, with hyphens changed to underscores and letters
converted to uppercase. <code>API_KEY_FILE</code> contains the mounted file path, not the key value.</p>
<h2 id="rotation-and-revocation">Rotation and revocation<a class="headerlink" href="#rotation-and-revocation" title="Permanent link">&para;</a></h2>
<p>During rotation, receive the new generation, update the vault or mounted file, and confirm
connectivity through the harmless <code>/rpc/ping</code> route. The server owner revokes the previous
generation only after this confirmation.</p>
<p>A <code>401</code> means the key is missing, unknown, expired, or revoked. A <code>503</code> means the authorization
service or registry is unavailable. In either case, do not bypass REST or weaken TLS verification.</p>
<br>
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
<div class="wm-article-nav pull-right">
<a href="../dwh-auth-tls/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../dwh-auth-tls/" class="btn btn-xs btn-link">
TLS
</a>
</div>
<div class="wm-article-nav">
<a href="../dwh-auth-server/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../dwh-auth-server/" class="btn btn-xs btn-link">
Server
</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>
+160
View File
@@ -0,0 +1,160 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta content="IE=edge" http-equiv="X-UA-Compatible"/>
<meta content="width=device-width, initial-scale=1.0" name="viewport"/>
<link href="https://git.tylconsulting.it/thothii-docs/install/dwh-auth-server/" rel="canonical"/>
<link href="../../img/favicon.ico" rel="shortcut icon"/>
<meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" name="viewport"/>
<title>Server - 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 href="../../css/highlight.css" rel="stylesheet"/>
<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: "dwh-auth: server guide", url: "#_top", children: [
{title: "Security boundaries", url: "#security-boundaries" },
{title: "Installation", url: "#installation" },
{title: "Creating and revoking keys", url: "#creating-and-revoking-keys" },
{title: "Nginx integration", url: "#nginx-integration" },
]},
];
</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 aria-label="navigation" class="row wm-article-nav-buttons" role="navigation">
<div class="wm-article-nav pull-right">
<a class="btn btn-xs btn-default pull-right" href="../dwh-auth-client-enrollment/">
Next
<i aria-hidden="true" class="fa fa-chevron-right"></i>
</a>
<a class="btn btn-xs btn-link" href="../dwh-auth-client-enrollment/">
Client enrollment
</a>
</div>
<div class="wm-article-nav">
<a class="btn btn-xs btn-default pull-left" href="../../usage/memory/">
<i aria-hidden="true" class="fa fa-chevron-left"></i>
Previous</a><a class="btn btn-xs btn-link" href="../../usage/memory/">
Memory
</a>
</div>
</div>
<h1 id="dwh-auth-server-guide"><code>dwh-auth</code>: server guide<a class="headerlink" href="#dwh-auth-server-guide" title="Permanent link"></a></h1>
<p><code>dwh-auth</code> protects the REST <code>/dwh/</code> route with a separate key for each ThothII installation.
It runs as a separate Linux service, does not read DWH data, and does not connect directly to
PostgreSQL.</p>
<div class="mermaid">flowchart LR
CLIENT["Installazione ThothII"] --&gt;|"X-API-Key"| NGINX["Nginx"]
NGINX --&gt; AUTH["dwh-auth\nUnix socket"]
AUTH --&gt; REGISTRY["Registro chiavi\nactive e revoked"]
AUTH --&gt;|"authorized"| REST["DWH REST"]
</div>
<h2 id="security-boundaries">Security boundaries<a class="headerlink" href="#security-boundaries" title="Permanent link"></a></h2>
<ul>
<li>A key identifies an installation, not a person.</li>
<li>Keys and backups stay in protected files and never enter Git, logs, arguments, or public JSON.</li>
<li>The registry stores digests and metadata, never the key in plaintext.</li>
<li>The REST route must be exposed only through verified TLS.</li>
</ul>
<h2 id="installation">Installation<a class="headerlink" href="#installation" title="Permanent link"></a></h2>
<p>Il servizio usa questi percorsi:</p>
<table>
<thead>
<tr>
<th>Oggetto</th>
<th>Percorso</th>
</tr>
</thead>
<tbody>
<tr>
<td>Binario</td>
<td><code>/usr/local/sbin/dwh-auth</code></td>
</tr>
<tr>
<td>Unit systemd</td>
<td><code>/etc/systemd/system/dwh-auth.service</code></td>
</tr>
<tr>
<td>Registro</td>
<td><code>/var/lib/dwh-auth/</code></td>
</tr>
<tr>
<td>Socket</td>
<td><code>/run/dwh-auth/verify.sock</code></td>
</tr>
<tr>
<td>Consegne protette</td>
<td><code>/root/dwh-auth-provision/</code></td>
</tr>
</tbody>
</table>
<p>Install the binary and unit with <code>root</code> ownership, create the <code>dwh-auth</code> service user, and enable
the unit with <code>systemctl enable --now dwh-auth</code>. The socket must be accessible to Nginx's group.</p>
<h2 id="creating-and-revoking-keys">Creating and revoking keys<a class="headerlink" href="#creating-and-revoking-keys" title="Permanent link"></a></h2>
<p>Esempio per l'installazione ACME Limited:</p>
<pre class="highlight"><code class="language-bash">sudo dwh-auth --registry-root /var/lib/dwh-auth key create \
--installation-id acme-factory-primary \
--description acme-factory-primary \
--output /root/dwh-auth-provision/acme-factory-primary.key</code></pre>
<p>Deliver the file through an enterprise vault or an authenticated channel. To rotate a key, create
a new one, distribute it, update the client, and revoke the old one using its public ID:</p>
<pre class="highlight"><code class="language-bash">sudo dwh-auth --registry-root /var/lib/dwh-auth key revoke \
--key-id PUBLIC_KEY_ID \
--reason scheduled-rotation</code></pre>
<p>Revocation is permanent. Keep encrypted registry backups before every mutation.</p>
<h2 id="nginx-integration">Nginx integration<a class="headerlink" href="#nginx-integration" title="Permanent link"></a></h2>
<p>Nginx forwards the key to the <code>dwh-auth</code> socket. Only an authorized response allows the request
to reach DWH REST. Missing, unknown, expired, or revoked keys receive <code>401</code>; an unavailable
service or registry produces <code>503</code>.</p>
<br/>
<div aria-label="navigation" class="row wm-article-nav-buttons" role="navigation">
<div class="wm-article-nav pull-right">
<a class="btn btn-xs btn-default pull-right" href="../dwh-auth-client-enrollment/">
Next
<i aria-hidden="true" class="fa fa-chevron-right"></i>
</a>
<a class="btn btn-xs btn-link" href="../dwh-auth-client-enrollment/">
Client enrollment
</a>
</div>
<div class="wm-article-nav">
<a class="btn btn-xs btn-default pull-left" href="../../usage/memory/">
<i aria-hidden="true" class="fa fa-chevron-left"></i>
Previous</a><a class="btn btn-xs btn-link" href="../../usage/memory/">
Memory
</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>
<script type="module">import mermaid from "https://unpkg.com/mermaid@10.4.0/dist/mermaid.esm.min.mjs";
mermaid.initialize({});</script></body>
</html>
+131
View File
@@ -0,0 +1,131 @@
<!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/dwh-auth-tls/">
<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>TLS - 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: "TLS for DWH REST", url: "#_top", children: [
{title: "Private CA", url: "#private-ca" },
{title: "Out-of-band fingerprint", url: "#out-of-band-fingerprint" },
{title: "Renewal", url: "#renewal" },
]},
];
</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">
<a href="../dwh-auth-client-enrollment/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../dwh-auth-client-enrollment/" class="btn btn-xs btn-link">
Client enrollment
</a>
</div>
</div>
<h1 id="tls-for-dwh-rest">TLS for DWH REST<a class="headerlink" href="#tls-for-dwh-rest" title="Permanent link">&para;</a></h1>
<p>The DWH key may be used only over verified TLS. Authorization or availability errors never justify
disabling certificate verification.</p>
<h2 id="private-ca">Private CA<a class="headerlink" href="#private-ca" title="Permanent link">&para;</a></h2>
<p>When DWH REST uses an enterprise CA, deliver the certificate separately from the API key. The CA
is not a credential, but its integrity is part of the security boundary. Keep it out of Git and
make it unwritable by unauthorized users.</p>
<p>Esempio ACME Limited:</p>
<pre class="highlight"><code class="language-dotenv">THT_WS_ACME_EBIKES_DWH_TLS_CA_FILE=/run/secrets/acme-ebikes-dwh-ca.pem</code></pre>
<h2 id="out-of-band-fingerprint">Out-of-band fingerprint<a class="headerlink" href="#out-of-band-fingerprint" title="Permanent link">&para;</a></h2>
<p>Calculate the fingerprint of the received file and compare it through an independent channel:</p>
<pre class="highlight"><code class="language-bash">openssl x509 -noout -fingerprint -sha256 \
-in /absolute/protected/acme-ebikes-dwh-ca.pem</code></pre>
<p>The certificate SAN must include the exact name used by the binding, such as <code>dwh.acme.example</code>.</p>
<h2 id="renewal">Renewal<a class="headerlink" href="#renewal" title="Permanent link">&para;</a></h2>
<ol>
<li>Prepare the new certificate and chain.</li>
<li>Confirm the SAN and fingerprint out of band.</li>
<li>Distribute the new CA to clients while temporarily keeping the old one.</li>
<li>Update the binding and confirm connectivity with normal TLS.</li>
<li>Install the server certificate.</li>
<li>Remove the old trust after the agreed window.</li>
</ol>
<p>Do not use <code>curl -k</code>, disable TLS, or embed complete certificates or fingerprints in shared documents.</p>
<br>
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
<div class="wm-article-nav">
<a href="../dwh-auth-client-enrollment/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../dwh-auth-client-enrollment/" class="btn btn-xs btn-link">
Client enrollment
</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>
@@ -0,0 +1,39 @@
# Copy this file to a protected operator-controlled path named exactly thothii-installation.yaml
# and set mode 0600 (or 0400) before using it as THT_INSTALLATION_CONFIG_SOURCE.
# Replace every absolute placeholder. Select exactly one Git transport override.
schemaVersion: 2
profile: local
shell:
mode: full
defaultLocale: en
projectDirectory: "/absolute/path/to/ThothII"
envFile: "/absolute/path/to/ThothII/deploy/env/local.env"
workspaceRepository:
remote: git@git.example.com:organization/workspaces.git
branch: main
access: ssh
modelCatalog:
defaults:
session: deepseek/deepseek-v4-pro
metadataGeneration: openai/gpt-4.1-mini
embedding:
id: ollama/qwen3-embedding:0.6b
dimensions: 1024
providers:
deepseek:
authentication: {mode: pi_auth}
session: {mode: pi_builtin}
models:
deepseek-v4-pro:
session: {}
openai:
authentication: {mode: secret_env, apiKeyEnv: OPENAI_API_KEY}
metadataGeneration: {litellmProvider: openai}
models:
gpt-4.1-mini:
label: OpenAI Mini
metadataGeneration: {}
authentication:
configDirectory: "/absolute/path/to/thothii-auth"
overrides:
- "/absolute/path/to/ThothII/deploy/compose.git-ssh.yaml"
@@ -0,0 +1,49 @@
# Copy this file to a protected operator path named exactly thothii-installation.yaml
# and set mode 0600 (or 0400) before using it as THT_INSTALLATION_CONFIG_SOURCE.
# Replace every absolute placeholder. Select exactly one Git transport override.
schemaVersion: 2
profile: server
# Standalone server with protected direct OIDC auth, not the Omics upstream path.
# For Omics use authentication-upstream.md: embedded, no auth runtime projection.
shell:
mode: full
defaultLocale: en
projectDirectory: "/absolute/path/to/ThothII"
envFile: "/absolute/path/to/thothii-server-operator/server.env"
workspaceRepository:
remote: git@git.example.com:organization/workspaces.git
branch: main
access: ssh
modelCatalog:
defaults:
session: deepseek/deepseek-v4-pro
metadataGeneration: openai/gpt-4.1-mini
embedding:
id: ollama/qwen3-embedding:0.6b
dimensions: 1024
providers:
deepseek:
authentication: {mode: pi_auth}
session: {mode: pi_builtin}
models:
deepseek-v4-pro:
session: {}
openai:
endpoint: {baseUrl: https://api.openai.example/v1}
authentication: {mode: secret_env, apiKeyEnv: OPENAI_API_KEY}
metadataGeneration: {litellmProvider: openai}
models:
gpt-4.1-mini:
label: OpenAI Mini
metadataGeneration: {}
authentication:
# Root-operated source of truth; it is never mounted into core.
configDirectory: "/srv/example/thothii/auth-canonical"
runtimeProjection:
# The only authentication bind exposed to core by the automatic override.
directory: "/srv/example/thothii/auth-runtime"
uid: 10001
gid: 10001
overrides:
- "/absolute/path/to/ThothII/deploy/compose.session-server.yaml.example"
- "/absolute/path/to/ThothII/deploy/compose.git-ssh.yaml"
@@ -0,0 +1,14 @@
# Copy to an untracked operator file. This file contains only non-secret THT_WS_* bindings.
# Every *_FILE value is a container path supplied by the generated local connector override.
THT_WS_NORTH_STAR_RESEARCH_DWH_TRANSPORT=postgres_direct
THT_WS_NORTH_STAR_RESEARCH_DWH_HOST=dwh.internal.example
THT_WS_NORTH_STAR_RESEARCH_DWH_PORT=5432
THT_WS_NORTH_STAR_RESEARCH_DWH_USER=thoth_reader
THT_WS_NORTH_STAR_RESEARCH_DWH_PASSWORD_FILE=/run/secrets/north-star-research-dwh-password
# Evidence examples use separate illustrative namespaces because one descriptor selects one mode.
# Values are container file paths only; signed URLs and credential contents stay in those files.
THT_WS_SIGNED_HTTP_EVIDENCE_SIGNED_URLS_FILE=/run/secrets/signed-http-evidence-urls.json
THT_WS_STATIC_S3_EVIDENCE_ACCESS_KEY_FILE=/run/secrets/static-s3-evidence-access-key
THT_WS_STATIC_S3_EVIDENCE_SECRET_KEY_FILE=/run/secrets/static-s3-evidence-secret-key
THT_WS_STATIC_S3_EVIDENCE_SESSION_TOKEN_FILE=/run/secrets/static-s3-evidence-session-token
+175
View File
@@ -0,0 +1,175 @@
<!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/first-start/">
<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>Start here - 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: "Install and first start", url: "#_top", children: [
{title: "What must be ready", url: "#what-must-be-ready" },
{title: "Follow the ordered procedure", url: "#follow-the-ordered-procedure" },
{title: "After startup", url: "#after-startup" },
]},
];
</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-it/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../standalone-manual-it/" class="btn btn-xs btn-link">
Mac, Windows, Linux — Italiano
</a>
</div>
<div class="wm-article-nav">
<a href="../../guida-utente/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../../guida-utente/" class="btn btn-xs btn-link">
User guide
</a>
</div>
</div>
<h1 id="install-and-first-start">Install and first start<a class="headerlink" href="#install-and-first-start" title="Permanent link">&para;</a></h1>
<p>Use one complete procedure for a fresh installation:</p>
<ul>
<li><a href="../standalone-manual-it/">Italian manual installation</a></li>
<li><a href="../standalone-manual-en/">English manual installation</a></li>
</ul>
<p>Both cover macOS, Windows through Ubuntu WSL2, and Linux. They use a Gitea clone,
protected local configuration and manual terminal commands, without an application
installer or launcher. See their verification matrix for tests still pending.</p>
<h2 id="what-must-be-ready">What must be ready<a class="headerlink" href="#what-must-be-ready" title="Permanent link">&para;</a></h2>
<p>You need Docker with Compose, the host operator command <code>tht</code>, access to the workspace
repository, and the credentials and network routes for the configured DWH and model
providers. Pi runs inside the application runtime; no host Pi installation is needed.</p>
<p>The stack includes <code>frontend</code>, <code>core</code>, <code>catalog-db</code>, <code>qdrant</code>, <code>embedding</code>, plus the
one-shot <code>embedding-model-init</code> and <code>catalog-migrate</code> services. DWH and generative-model
endpoints remain separate installation settings.</p>
<p>Secrets, certificates, Pi authentication and endpoint bindings are protected local files.
Do not commit them or copy the configuration of another machine unchanged.</p>
<h2 id="follow-the-ordered-procedure">Follow the ordered procedure<a class="headerlink" href="#follow-the-ordered-procedure" title="Permanent link">&para;</a></h2>
<p>The bilingual guides provide the exact commands for:</p>
<ol>
<li>Cloning the selected revision and checking prerequisites.</li>
<li>Bootstrapping the native host command.</li>
<li>Preparing catalog passwords and using
<code>tht setup --profile local --shell-mode full --shell-default-locale en --configure-only</code>.</li>
<li>Completing model, authentication and workspace credentials.</li>
<li>Generating configuration, building images and explicitly running <code>catalog-migrate</code>.</li>
<li>Starting the installation and checking health and readiness.</li>
</ol>
<p>Do not run setup alone as a substitute for that sequence. Migrations are not an
implicit effect of backend startup or <code>tht start</code>. Do not mix this installation's
descriptor/project with a different low-level Compose environment.</p>
<p>For an already configured installation:</p>
<pre class="highlight"><code class="language-sh">tht --installation /absolute/path/thothii-installation.yaml status
tht --installation /absolute/path/thothii-installation.yaml doctor --json</code></pre>
<p><code>/health</code> checks application-process readiness. Doctor also checks configuration,
workspace, workflow and Pi prerequisites; a healthy web page alone does not prove
that a real database question can complete.</p>
<h2 id="after-startup">After startup<a class="headerlink" href="#after-startup" title="Permanent link">&para;</a></h2>
<p>Prepare <a href="../../operations/workspaces/">workspaces</a>, configure a database in
<a href="../../operations/database-management/">Database Management</a>, and complete the functional
checks in the installation guide before using real data.</p>
<p>See <a href="../shell-and-language/">display mode and language</a>, <a href="../authentication-local/">local authentication</a>,
<a href="../authentication-oidc/">OIDC</a> and <a href="../../general/pi-configuration/">model configuration</a>
for later changes. Embedded portal integration is separate from a fresh standalone setup.</p>
<p>Use the installation's normal <code>tht start</code>, <code>tht stop</code> and diagnostic commands.
Preserve its descriptor, credentials, database and persistent volumes; do not use
<code>down --volumes</code> as a routine stop or upgrade.</p>
<br>
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
<div class="wm-article-nav pull-right">
<a href="../standalone-manual-it/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../standalone-manual-it/" class="btn btn-xs btn-link">
Mac, Windows, Linux — Italiano
</a>
</div>
<div class="wm-article-nav">
<a href="../../guida-utente/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../../guida-utente/" class="btn btn-xs btn-link">
User guide
</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>
+199
View File
@@ -0,0 +1,199 @@
<!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/shell-and-language/">
<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>Display mode and language - 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: "Display mode and language", url: "#_top", children: [
{title: "Standalone setup", url: "#standalone-setup" },
{title: "Authentication and embedded deployments", url: "#authentication-and-embedded-deployments" },
{title: "Three different languages", url: "#three-different-languages" },
]},
];
</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="../authentication-local/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../authentication-local/" class="btn btn-xs btn-link">
Local authentication
</a>
</div>
<div class="wm-article-nav">
<a href="../standalone-manual-en/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../standalone-manual-en/" class="btn btn-xs btn-link">
Mac, Windows, Linux — English
</a>
</div>
</div>
<h1 id="display-mode-and-language">Display mode and language<a class="headerlink" href="#display-mode-and-language" title="Permanent link">&para;</a></h1>
<p>ThothII can run with its own application header (<strong>full</strong>) or inside an integrated
portal (<strong>embedded</strong>). Display mode and authentication are separate choices.</p>
<table>
<thead>
<tr>
<th>Installation</th>
<th>Display</th>
<th>Authentication</th>
</tr>
</thead>
<tbody>
<tr>
<td>Standalone local instance</td>
<td><code>full</code></td>
<td>Local ThothII account</td>
</tr>
<tr>
<td>Standalone server</td>
<td><code>full</code></td>
<td>Local accounts or configured OIDC provider</td>
</tr>
<tr>
<td>Integrated portal</td>
<td><code>embedded</code></td>
<td>Identity verified by the portal's trusted server proxy</td>
</tr>
</tbody>
</table>
<h2 id="standalone-setup">Standalone setup<a class="headerlink" href="#standalone-setup" title="Permanent link">&para;</a></h2>
<p>Follow the complete <a href="../standalone-manual-it/">Italian</a> or
<a href="../standalone-manual-en/">English</a> installation procedure. It explicitly selects
<code>--shell-mode full --shell-default-locale en</code> and separates configuration, credentials,
initial migrations and startup. Do not skip those steps by running setup alone.</p>
<p>The authored installation descriptor contains:</p>
<pre class="highlight"><code class="language-yaml">shell:
mode: full
defaultLocale: en</code></pre>
<p>Use <code>it</code> for an Italian initial interface. Existing browser language preferences can
override that initial value. Full mode remembers language and theme in the browser.</p>
<p>For an existing installation, preserve the current descriptor and edit only the intended
settings; do not rerun setup to overwrite it. With a current host <code>tht</code> binary:</p>
<pre class="highlight"><code class="language-sh">tht --installation /absolute/path/thothii-installation.yaml installation generate
tht --installation /absolute/path/thothii-installation.yaml start
tht --installation /absolute/path/thothii-installation.yaml status
tht --installation /absolute/path/thothii-installation.yaml doctor --json</code></pre>
<p>Generation updates derived configuration; it does not start services. <code>start</code> applies
the installation's normal lifecycle and is not guaranteed to touch only the frontend.
Follow the deployment's maintenance procedure and retain its network, authentication and
model settings. Do not edit generated files or remove persistent volumes.</p>
<h2 id="authentication-and-embedded-deployments">Authentication and embedded deployments<a class="headerlink" href="#authentication-and-embedded-deployments" title="Permanent link">&para;</a></h2>
<p>Full mode does not configure login by itself. See <a href="../authentication-local/">local authentication</a>
or <a href="../authentication-oidc/">OIDC</a>, with <a href="../authentik/">Authentik</a> as a provider option.</p>
<p>Embedded mode requires a compatible portal integration, not just a descriptor toggle.
The portal owns login/logout and supplies a server-verified identity. A presentation
adapter does not authenticate users. The core must not be reachable by a route that
bypasses the trusted proxy. Do not add a second OIDC login to an already authenticated
upstream deployment.</p>
<p>Portal implementation details belong to the
<a href="https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/install/authentication-upstream.md">developer integration reference in the repository</a>,
not to the standalone installation procedure.</p>
<h2 id="three-different-languages">Three different languages<a class="headerlink" href="#three-different-languages" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Interface language</strong> controls labels, forms and application messages.</li>
<li><strong>Session interaction language</strong> is captured when a session is created. Resuming it
retains that language even if the interface language changes later.</li>
<li><strong>Workspace language</strong> concerns domain content and retrieval; switching the interface
does not translate Evidence, SQL, identifiers or database values.</li>
</ul>
<p>In embedded mode the interface follows the portal's language and theme. A portal language
change may reload the page. Saved session artifacts remain available, but resuming work
is explicit; a reload does not by itself request a new model generation.</p>
<br>
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
<div class="wm-article-nav pull-right">
<a href="../authentication-local/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../authentication-local/" class="btn btn-xs btn-link">
Local authentication
</a>
</div>
<div class="wm-article-nav">
<a href="../standalone-manual-en/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../standalone-manual-en/" class="btn btn-xs btn-link">
Mac, Windows, Linux — English
</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>
+466
View File
@@ -0,0 +1,466 @@
<!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-en/">
<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 — English - 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: "Manual standalone installation", url: "#_top", children: [
{title: "Verification matrix", url: "#verification-matrix" },
{title: "Before you start", url: "#before-you-start" },
{title: "1. Clone a project revision", url: "#1-clone-a-project-revision" },
{title: "2. Check prerequisites and install the operator command", url: "#2-check-prerequisites-and-install-the-operator-command" },
{title: "3. Configure and start the local installation", url: "#3-configure-and-start-the-local-installation" },
{title: "4. Verify the installation", url: "#4-verify-the-installation" },
{title: "Daily lifecycle", url: "#daily-lifecycle" },
{title: "Quick diagnosis", url: "#quick-diagnosis" },
{title: "Acceptance checklist", url: "#acceptance-checklist" },
{title: "Out of scope for this release", url: "#out-of-scope-for-this-release" },
{title: "Related documents", url: "#related-documents" },
]},
];
</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="../shell-and-language/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../shell-and-language/" class="btn btn-xs btn-link">
Display mode and language
</a>
</div>
<div class="wm-article-nav">
<a href="../standalone-manual-it/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../standalone-manual-it/" class="btn btn-xs btn-link">
Mac, Windows, Linux — Italiano
</a>
</div>
</div>
<h1 id="manual-standalone-installation">Manual standalone installation<a class="headerlink" href="#manual-standalone-installation" title="Permanent link">&para;</a></h1>
<p><a href="../standalone-manual-it/">Versione italiana</a></p>
<p>This is the verification procedure for preparing THothII as a standalone application in <code>full</code>
mode on macOS, Windows, and Linux.</p>
<p>In this document, “standalone” means that the user does not need to install Node.js, Python or Pi
on the host: the application services and local semantic
services run through Docker. DWH and LLM providers remain external endpoints configured by the
installation; this is not an offline package.</p>
<p>This path uses no graphical installer, native launcher, or Docker Hub image. It starts from a Gitea
clone and uses explicit terminal commands. Publishing pre-built images is a later step.</p>
<h2 id="verification-matrix">Verification matrix<a class="headerlink" href="#verification-matrix" title="Permanent link">&para;</a></h2>
<table>
<thead>
<tr>
<th>System</th>
<th>Recommended terminal</th>
<th>Runtime</th>
<th>Test architecture</th>
</tr>
</thead>
<tbody>
<tr>
<td>macOS supported by the installed Docker Desktop version</td>
<td>Bash in Terminal</td>
<td>Docker Desktop</td>
<td>Apple Silicon (<code>arm64</code>)</td>
</tr>
<tr>
<td>Windows 11</td>
<td>Ubuntu inside WSL2</td>
<td>Docker Desktop with WSL2 integration</td>
<td>x64 (<code>amd64</code>)</td>
</tr>
<tr>
<td>Ubuntu Linux 22.04 or 24.04</td>
<td>Bash</td>
<td>Docker Engine + Compose v2</td>
<td>x64 (<code>amd64</code>)</td>
</tr>
</tbody>
</table>
<p>Intel macOS is excluded from the first verification campaign. ARM Linux may be tested when the
machine’s Docker runtime reports <code>arm64</code>, but it is not part of the minimum matrix.</p>
<p>Documentation and Mac prerequisite checks have passed. Complete fresh installations on all three
systems remain pending; this matrix describes the tests to perform, not completed certification.</p>
<h2 id="before-you-start">Before you start<a class="headerlink" href="#before-you-start" title="Permanent link">&para;</a></h2>
<p>You need:</p>
<ul>
<li>access to the THothII Gitea repository and the workspace Git repository;</li>
<li>Git;</li>
<li>Docker Desktop on macOS and Windows, or Docker Engine with the Compose v2 plugin on Linux;</li>
<li>Bash, <code>curl</code>, OpenSSL and <code>shasum</code> (Ubuntu package: <code>libdigest-sha-perl</code>);</li>
<li>enough disk space to build the images and download the embedding model;</li>
<li>the DWH and LLM endpoints, plus the credentials required by the installation.</li>
</ul>
<p>On Linux, the current user must be able to run Docker. If the system requires <code>sudo</code>, add the user
to the Docker group according to local policy and open a new session before continuing.</p>
<p>On Windows, run every command in this guide from Ubuntu under WSL2. In Docker Desktop, enable WSL2
integration for that distribution. Clone the project inside the WSL2 Linux filesystem, for example
under <code>~/src</code>, rather than under <code>/mnt/c</code>: this avoids slow builds and path/line-ending issues. Pi
does not need to be installed on the host.</p>
<p>Check the runtime before or immediately after cloning:</p>
<pre class="highlight"><code class="language-sh">docker version
docker compose version
docker version --format '{{.Server.Arch}}'</code></pre>
<p>The last command must return <code>amd64</code>, <code>x86_64</code>, <code>arm64</code>, or <code>aarch64</code>.</p>
<h2 id="1-clone-a-project-revision">1. Clone a project revision<a class="headerlink" href="#1-clone-a-project-revision" title="Permanent link">&para;</a></h2>
<p>Use the project repository on 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>For an SSH clone, when the key is already authorized on Gitea:</p>
<pre class="highlight"><code class="language-sh">git clone git@git.tylconsulting.it:mptyl/ThothII.git</code></pre>
<p>Record the hash printed by <code>git rev-parse</code> for a repeatable test. In a later campaign, use the
maintainer-approved revision/tag rather than implicitly following a mutable <code>main</code> branch.</p>
<h2 id="2-check-prerequisites-and-install-the-operator-command">2. Check prerequisites and install the operator command<a class="headerlink" href="#2-check-prerequisites-and-install-the-operator-command" title="Permanent link">&para;</a></h2>
<p>From the clone root:</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> bootstraps only the native <code>tht</code> operator command; it does not install a desktop
version of THothII. It uses the repository’s Docker builder, installs the binary for the current
terminal environment, and installs it in the user directory. Persist <code>$HOME/.local/bin</code> in your
shell PATH for new terminals too. An existing <code>tht</code> in this directory will be updated.</p>
<p>On Windows, run these commands inside WSL2. The installed <code>tht</code> binary is the Linux binary inside
WSL2; the application runtime remains Docker Desktop. Do not use <code>scripts/install-tht.ps1</code> as the
primary path for this test.</p>
<h2 id="3-configure-and-start-the-local-installation">3. Configure and start the local installation<a class="headerlink" href="#3-configure-and-start-the-local-installation" title="Permanent link">&para;</a></h2>
<p>Run the remaining blocks in one Bash session from the physical clone root (<code>pwd -P</code>).
First create two distinct catalog passwords, preserving any existing files:</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 &gt; "$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>Do not regenerate passwords for an initialized catalog. Configure without starting services:</p>
<pre class="highlight"><code class="language-sh">tht setup --profile local --shell-mode full --shell-default-locale en --configure-only</code></pre>
<p>Answer the prompts as follows:</p>
<table>
<thead>
<tr>
<th>Prompt</th>
<th>Value or rule</th>
</tr>
</thead>
<tbody>
<tr>
<td>Installation ID</td>
<td><code>local</code>, unless one clone hosts multiple installations</td>
</tr>
<tr>
<td>Deployment profile</td>
<td><code>local</code></td>
</tr>
<tr>
<td>DWH API endpoint</td>
<td>An <code>http(s)</code> URL without user, password, query, or fragment; may be empty for a smoke-only test</td>
</tr>
<tr>
<td>LLM API endpoint</td>
<td>An <code>http(s)</code> URL without credentials; may be empty for a smoke-only test</td>
</tr>
<tr>
<td>Workspace repository URL</td>
<td>The workspace repository URL, not the THothII source clone</td>
</tr>
<tr>
<td>Workspace branch</td>
<td>Normally <code>main</code></td>
</tr>
<tr>
<td>Workspace access</td>
<td><code>ssh</code> with a deploy key, or <code>https</code> with a protected credential file</td>
</tr>
<tr>
<td>File paths</td>
<td>Accept the default paths under <code>deploy/local/secrets/</code> for the first test</td>
</tr>
<tr>
<td>Secret templates</td>
<td>Answer <code>yes</code> when protected files do not exist yet</td>
</tr>
<tr>
<td>Authentication</td>
<td>Configure the local login required by the installation; never put passwords on a command line</td>
</tr>
</tbody>
</table>
<p>The generated configuration is local and ignored by 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>Edit secrets only in protected local files; never commit them. <code>deploy/env/local.env.example</code> is a tracked reference; the
generated path <code>deploy/local/operator.env</code> is the active path for this installation.</p>
<h3 id="complete-protected-files">Complete protected files<a class="headerlink" href="#complete-protected-files" title="Permanent link">&para;</a></h3>
<p>If setup created blank templates, enter the values with a local editor:</p>
<pre class="highlight"><code class="language-sh">chmod 600 deploy/local/secrets/*
"${EDITOR:-vi}" deploy/local/secrets/thothii.secrets</code></pre>
<p>The bundle must contain only <code>KEY=VALUE</code> lines for credentials actually used by <code>modelCatalog</code>. The
allowed names and credential boundary are documented in the local file
<code>deploy/secrets/README.md</code>. Do not put tokens in URLs, the YAML
descriptor, the Git repository, or commands copied into the shell.</p>
<p>For SSH workspace access, also provide the private key and <code>known_hosts</code> file requested by setup.
For HTTPS access, provide the Git credential file and any required CA. Both must remain protected
and outside version control.</p>
<p>Before starting, complete these additional configuration steps:</p>
<ol>
<li>Add <code>THT_CATALOG_RUNTIME_PASSWORD_SOURCE</code> and <code>THT_CATALOG_MIGRATOR_PASSWORD_SOURCE</code> to
<code>deploy/local/operator.env</code>, with the same absolute paths exported above. Setup does not persist
these two variables. Store paths, not passwords.</li>
<li>Replace the descriptor's generic <code>modelCatalog</code> with the approved provider/model configuration.
The generated defaults do not replicate the existing Mac. See <a href="../../general/pi-configuration/">Pi/model configuration</a>
and the local example <code>deploy/psd/thothii-installation.yaml.example</code>.</li>
<li>Populate the keys referenced by <code>authentication.apiKeyEnv</code> in <code>thothii.secrets</code>. Providers using
<code>pi_auth</code> need valid credentials at <code>PI_AUTH_FILE</code>; the <code>{}</code> template is not authentication.</li>
<li>Complete the workspace Git files. SSH requires an authorized deploy key and verified known-hosts;
HTTPS requires the credential file and CA bundle expected by the overlay. Blank templates cannot
provide repository access.</li>
</ol>
<p>After editing generated configuration, do not rerun setup: it rejects different existing content.
Generate the projections and run the explicit migration below. Use <code>THT_GIT_ACCESS=https</code> if that
was selected during setup. This block targets the fresh <code>local</code> descriptor with only the Git overlay;
custom installations must include their extra descriptor overlays in the same order.</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>Stop if a command fails. The project name matches the hash used by <code>tht</code>, preserving volume
identity. <code>catalog-migrate</code> applies Catalog and Memory migrations; <code>tht start</code> does not run it
automatically. Initial embedding-model download may take time. Use this installation-specific
sequence, not <code>run-stack.sh</code> with a different environment/project name.</p>
<h2 id="4-verify-the-installation">4. Verify the installation<a class="headerlink" href="#4-verify-the-installation" title="Permanent link">&para;</a></h2>
<p>The descriptor generated for the default ID is:</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>The verifier is read-only: it runs <code>tht doctor --json</code> and <code>tht status</code> without restarting the
stack, regenerating configuration, or printing secret contents.</p>
<h3 id="gate-a-platform-smoke-test-on-all-three-computers">Gate A — platform smoke test on all three computers<a class="headerlink" href="#gate-a-platform-smoke-test-on-all-three-computers" title="Permanent link">&para;</a></h3>
<p>Record the following for each machine:</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>The gate passes when the clone is intact, Docker and Compose are reachable, <code>tht doctor</code> is OK, the
stack is running, and the frontend responds at the default local URL <code>http://127.0.0.1:8080</code>.
Doctor also checks workspace and Pi: record their failures separately rather than labeling every
failure as a platform problem. Check HTTP readiness with:</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-functional-verification">Gate B — functional verification<a class="headerlink" href="#gate-b-functional-verification" title="Permanent link">&para;</a></h3>
<p>Run this on at least one machine with available endpoints and credentials:</p>
<p>First follow <a href="../../operations/workspaces/">Workspace operations</a> to import/prepare the workspace
and configure the Database and local binding. The source clone does not transfer catalog data,
secrets or sessions from the Mac. Connect any VPN required by DWH/model endpoints and verify
that their names are reachable from containers too.</p>
<ol>
<li>open <code>http://127.0.0.1:8080</code>;</li>
<li>sign in with the configured local account;</li>
<li>verify that the configured workspace is readable;</li>
<li>start a real question and complete the review gates through final SQL;</li>
<li>stop and restart the installation, then run <code>verify-standalone-install.sh</code> again.</li>
</ol>
<p>A Gate B failure involving DWH, the LLM provider, workspace Git, or credentials does not by itself
prove a Docker portability problem: record the failed endpoint or component separately.</p>
<h2 id="daily-lifecycle">Daily lifecycle<a class="headerlink" href="#daily-lifecycle" title="Permanent link">&para;</a></h2>
<p>Use the explicit descriptor when more than one installation may be discoverable:</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>Use <code>start --build</code> after source changes or to rebuild images from the current checkout. <code>stop</code>
preserves volumes, sessions, the catalog, Pi state, Qdrant data, and the embedding model. Do not
use <code>docker compose down --volumes</code> during a normal test: it is destructive and removes local data.
For upgrades requiring migrations, follow the release runbook before starting the new application.</p>
<h2 id="quick-diagnosis">Quick diagnosis<a class="headerlink" href="#quick-diagnosis" title="Permanent link">&para;</a></h2>
<table>
<thead>
<tr>
<th>Symptom</th>
<th>Check</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Docker Engine is not reachable</code></td>
<td>start Docker Desktop or the Docker service and rerun <code>docker info</code></td>
</tr>
<tr>
<td>Windows sees Docker but Bash fails</td>
<td>run the guide inside Ubuntu WSL2 and enable that distribution in Docker Desktop</td>
</tr>
<tr>
<td><code>tht: command not found</code></td>
<td>open a new shell and check <code>command -v tht</code>; rerun the bootstrap if needed</td>
</tr>
<tr>
<td>line-ending or executable-script errors</td>
<td>use a clone in the WSL2/Linux filesystem and rerun <code>bash scripts/...</code></td>
</tr>
<tr>
<td>unsupported architecture</td>
<td>check <code>docker version --format '{{.Server.Arch}}'</code>; the test requires <code>amd64</code> or <code>arm64</code></td>
</tr>
<tr>
<td>missing descriptor or env file</td>
<td>use <code>deploy/local/...</code> generated by <code>tht setup</code>, not an arbitrary copied file</td>
</tr>
<tr>
<td>healthy stack but workflow failure</td>
<td>check external URLs, the credential bundle, workspace Git, and authentication separately</td>
</tr>
<tr>
<td>data appears missing</td>
<td>check that <code>down --volumes</code> was not used; <code>stop</code> does not remove volumes</td>
</tr>
</tbody>
</table>
<h2 id="acceptance-checklist">Acceptance checklist<a class="headerlink" href="#acceptance-checklist" title="Permanent link">&para;</a></h2>
<ul>
<li>[ ] The clone comes from the expected Gitea repository and the revision is recorded.</li>
<li>[ ] Docker Desktop/Engine and Compose v2 are available.</li>
<li>[ ] The runtime reports an allowed architecture.</li>
<li>[ ] <code>tht</code> was built from the repository and responds to <code>tht version</code>.</li>
<li>[ ] Setup uses <code>profile: local</code>, <code>shell.mode: full</code>, and <code>shell.defaultLocale: en</code>.</li>
<li>[ ] The descriptor, <code>operator.env</code>, authentication, and secrets exist only under <code>deploy/local/</code>.</li>
<li>[ ] No secret appears in Git, URLs, public YAML, or recorded commands.</li>
<li>[ ] Gate A passes on Apple Silicon macOS, x64 Windows WSL2, and x64 Linux.</li>
<li>[ ] Gate B runs on at least one machine with DWH and LLM available.</li>
<li>[ ] Stop/start and final verification complete without deleting volumes.</li>
</ul>
<h2 id="out-of-scope-for-this-release">Out of scope for this release<a class="headerlink" href="#out-of-scope-for-this-release" title="Permanent link">&para;</a></h2>
<p>The following remain future work:</p>
<ul>
<li>publishing pre-built images on Docker Hub;</li>
<li>reducing prompts through a dedicated non-interactive configuration;</li>
<li>creating DMG, MSI/EXE, AppImage, or other native installers;</li>
<li>providing an offline runtime or bundling a local DWH/LLM into the application.</li>
</ul>
<h2 id="related-documents">Related documents<a class="headerlink" href="#related-documents" title="Permanent link">&para;</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="../shell-and-language/" class="btn btn-xs btn-default pull-right">
Next
<i class="fa fa-chevron-right" aria-hidden="true"></i>
</a>
<a href="../shell-and-language/" class="btn btn-xs btn-link">
Display mode and language
</a>
</div>
<div class="wm-article-nav">
<a href="../standalone-manual-it/" class="btn btn-xs btn-default pull-left">
<i class="fa fa-chevron-left" aria-hidden="true"></i>
Previous</a><a href="../standalone-manual-it/" class="btn btn-xs btn-link">
Mac, Windows, Linux — Italiano
</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>
+471
View File
@@ -0,0 +1,471 @@
<!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">&para;</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">&para;</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">&para;</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">&para;</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">&para;</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">&para;</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 &gt; "$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">&para;</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">&para;</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">&para;</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">&para;</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">&para;</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">&para;</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">&para;</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">&para;</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">&para;</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>