Publish documentation for 2f53512e4d
This commit is contained in:
@@ -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">¶</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">¶</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 <operator-user> --admin-display-name <display-name> \
|
||||
--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">¶</a></h2>
|
||||
<pre class="highlight"><code class="language-sh">tht auth user list [--json]
|
||||
tht auth user add <username> --role user|admin [--display-name <name>] [--password-file <file>]
|
||||
tht auth user set-password <username> [--password-file <file>]
|
||||
tht auth user enable <username>
|
||||
tht auth user disable <username>
|
||||
tht auth user grant <username> --role user|admin
|
||||
tht auth user revoke <username> --role user|admin
|
||||
tht auth user logout-all <username> --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">¶</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">¶</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>
|
||||
@@ -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">¶</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><publicUrl>/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 <https-public-origin> \
|
||||
--issuer <https-issuer> --client-id <client-id> \
|
||||
--authentik-base-url <https-provider-origin> \
|
||||
--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: <https-public-origin>
|
||||
session:
|
||||
regularTtlSeconds: 43200
|
||||
regularIdleSeconds: 7200
|
||||
rememberTtlSeconds: 2592000
|
||||
rememberIdleSeconds: 604800
|
||||
oidcTtlSeconds: 28800
|
||||
oidc:
|
||||
issuer: <https-issuer>
|
||||
clientId: <client-id>
|
||||
clientSecretRef: THT_OIDC_CLIENT_SECRET
|
||||
scopes: [openid, profile, email]
|
||||
groupsClaim: groups
|
||||
groupCatalog:
|
||||
driver: authentik
|
||||
baseUrl: <https-provider-origin>
|
||||
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">¶</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">¶</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">¶</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>
|
||||
@@ -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->>ThothII: Sign in
|
||||
ThothII->>Authentik: Authorization Code with PKCE
|
||||
Authentik-->>Browser: Login and consent
|
||||
Browser->>ThothII: Callback with code
|
||||
ThothII->>Authentik: Token exchange
|
||||
Authentik-->>ThothII: Identity and groups
|
||||
ThothII-->>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">¶</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">¶</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">¶</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">¶</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>
|
||||
@@ -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"] -->|"X-API-Key"| NGINX["Nginx"]
|
||||
NGINX --> AUTH["dwh-auth\nUnix socket"]
|
||||
AUTH --> REGISTRY["Registro chiavi\nactive e revoked"]
|
||||
AUTH -->|"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>
|
||||
@@ -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">¶</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">¶</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">¶</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">¶</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
|
||||
@@ -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">¶</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">¶</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">¶</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">¶</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>
|
||||
@@ -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">¶</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">¶</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">¶</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">¶</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>
|
||||
@@ -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">¶</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">¶</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">¶</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">¶</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">¶</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">¶</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 > "$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">¶</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">¶</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">¶</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">¶</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">¶</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">¶</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">¶</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">¶</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">¶</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>
|
||||
@@ -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">¶</a></h1>
|
||||
<p><a href="../standalone-manual-en/">English version</a></p>
|
||||
<p>Questa è la procedura di prova per predisporre THothII come applicazione autonoma in modalità
|
||||
<code>full</code> su macOS, Windows e Linux.</p>
|
||||
<p>In questo documento “autonoma” significa che l’utente non deve installare Node.js, Python o Pi
|
||||
sull'host: i servizi applicativi e i servizi semantici
|
||||
locali vengono eseguiti con Docker. DWH e provider LLM restano endpoint esterni configurati
|
||||
dall’installazione; questa procedura non è un pacchetto offline.</p>
|
||||
<p>Il percorso non usa installer grafici, launcher nativi o immagini Docker Hub. Si parte da un clone
|
||||
Gitea e si usano comandi espliciti da terminale. La pubblicazione di immagini pre-costruite è una
|
||||
fase successiva.</p>
|
||||
<h2 id="matrice-di-verifica">Matrice di verifica<a class="headerlink" href="#matrice-di-verifica" title="Permanent link">¶</a></h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Sistema</th>
|
||||
<th>Terminale raccomandato</th>
|
||||
<th>Runtime</th>
|
||||
<th>Architettura della prova</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>macOS supportato dalla versione Docker Desktop installata</td>
|
||||
<td>Bash nel Terminale</td>
|
||||
<td>Docker Desktop</td>
|
||||
<td>Apple Silicon (<code>arm64</code>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Windows 11</td>
|
||||
<td>Ubuntu dentro WSL2</td>
|
||||
<td>Docker Desktop con integrazione WSL2</td>
|
||||
<td>x64 (<code>amd64</code>)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Linux Ubuntu 22.04 o 24.04</td>
|
||||
<td>Bash</td>
|
||||
<td>Docker Engine + Compose v2</td>
|
||||
<td>x64 (<code>amd64</code>)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Intel macOS non fa parte della prima campagna di verifica. ARM Linux può essere provato quando il
|
||||
runtime Docker della macchina restituisce <code>arm64</code>, ma non è un requisito della matrice minima.</p>
|
||||
<p>Le verifiche documentali e dei prerequisiti Mac sono passate. Le installazioni complete da zero
|
||||
sui tre sistemi restano da eseguire: la matrice indica le prove previste, non una certificazione.</p>
|
||||
<h2 id="cosa-serve-prima-di-iniziare">Cosa serve prima di iniziare<a class="headerlink" href="#cosa-serve-prima-di-iniziare" title="Permanent link">¶</a></h2>
|
||||
<p>Servono:</p>
|
||||
<ul>
|
||||
<li>accesso al repository Gitea di THothII e al repository Git dei workspace;</li>
|
||||
<li>Git;</li>
|
||||
<li>Docker Desktop su macOS e Windows, oppure Docker Engine con il plugin Compose v2 su Linux;</li>
|
||||
<li>Bash, <code>curl</code>, OpenSSL e <code>shasum</code> (su Ubuntu, pacchetto <code>libdigest-sha-perl</code>);</li>
|
||||
<li>spazio disco sufficiente per compilare le immagini e scaricare il modello di embedding;</li>
|
||||
<li>gli endpoint DWH e LLM, più le credenziali che l’installazione deve usare.</li>
|
||||
</ul>
|
||||
<p>Su Linux l’utente corrente deve poter eseguire Docker. Se il sistema richiede <code>sudo</code>, aggiungere
|
||||
l’utente al gruppo Docker secondo la policy locale e aprire una nuova sessione prima di continuare.</p>
|
||||
<p>Su Windows usare Ubuntu in WSL2 per tutti i comandi di questa guida. In Docker Desktop attivare
|
||||
l’integrazione WSL2 per quella distribuzione. Clonare il progetto nel filesystem Linux di WSL2,
|
||||
per esempio sotto <code>~/src</code>, e non sotto <code>/mnt/c</code>: si evitano rallentamenti e problemi di permessi o
|
||||
line ending. Non è necessario installare Pi sull’host.</p>
|
||||
<p>Verificare il runtime prima del clone o subito dopo:</p>
|
||||
<pre class="highlight"><code class="language-sh">docker version
|
||||
docker compose version
|
||||
docker version --format '{{.Server.Arch}}'</code></pre>
|
||||
<p>L’ultima istruzione deve restituire <code>amd64</code>, <code>x86_64</code>, <code>arm64</code> o <code>aarch64</code>.</p>
|
||||
<h2 id="1-clonare-una-revisione-del-progetto">1. Clonare una revisione del progetto<a class="headerlink" href="#1-clonare-una-revisione-del-progetto" title="Permanent link">¶</a></h2>
|
||||
<p>Usare il repository di progetto su Gitea:</p>
|
||||
<pre class="highlight"><code class="language-sh">mkdir -p "$HOME/src"
|
||||
cd "$HOME/src"
|
||||
git clone https://git.tylconsulting.it/mptyl/ThothII.git
|
||||
cd ThothII
|
||||
git rev-parse --short HEAD</code></pre>
|
||||
<p>Per un clone SSH usare, se la chiave è già autorizzata su Gitea:</p>
|
||||
<pre class="highlight"><code class="language-sh">git clone git@git.tylconsulting.it:mptyl/ThothII.git</code></pre>
|
||||
<p>Per una prova ripetibile annotare l’hash stampato da <code>git rev-parse</code>. In una campagna successiva
|
||||
usare la revisione/tag approvata dal maintainer invece di seguire implicitamente una <code>main</code> che
|
||||
può cambiare.</p>
|
||||
<h2 id="2-verificare-i-prerequisiti-e-installare-il-comando-operatore">2. Verificare i prerequisiti e installare il comando operatore<a class="headerlink" href="#2-verificare-i-prerequisiti-e-installare-il-comando-operatore" title="Permanent link">¶</a></h2>
|
||||
<p>Dal root del clone:</p>
|
||||
<pre class="highlight"><code class="language-sh">bash scripts/check-standalone-prerequisites.sh
|
||||
export PATH="$HOME/.local/bin:$PATH"
|
||||
THT_INSTALL_DIRECTORY="$HOME/.local/bin" bash scripts/install-tht.sh
|
||||
tht version</code></pre>
|
||||
<p><code>install-tht.sh</code> è un bootstrap del solo comando operatore nativo <code>tht</code>; non installa una versione
|
||||
desktop di THothII. Usa il builder Docker del repository, installa il binario adatto all’ambiente
|
||||
del terminale e lo installa nella directory utente. Aggiungere <code>$HOME/.local/bin</code> al PATH della
|
||||
shell anche per i terminali successivi. Un <code>tht</code> già presente in quella directory viene aggiornato.</p>
|
||||
<p>Su Windows, eseguire questi comandi dentro WSL2. Il binario <code>tht</code> installato è quello Linux di WSL2;
|
||||
il runtime dell’applicazione rimane Docker Desktop. Non usare <code>scripts/install-tht.ps1</code> come percorso
|
||||
principale di questa prova.</p>
|
||||
<h2 id="3-configurare-e-avviare-linstallazione-locale">3. Configurare e avviare l’installazione locale<a class="headerlink" href="#3-configurare-e-avviare-linstallazione-locale" title="Permanent link">¶</a></h2>
|
||||
<p>Eseguire i blocchi successivi nella stessa sessione Bash dal root fisico del clone (<code>pwd -P</code>).
|
||||
Creare prima le due password distinte del catalogo, conservando eventuali file già esistenti:</p>
|
||||
<pre class="highlight"><code class="language-bash">umask 077
|
||||
mkdir -p deploy/local/secrets
|
||||
for name in catalog-runtime-password catalog-migrator-password; do
|
||||
target="deploy/local/secrets/$name"
|
||||
if [ ! -e "$target" ]; then
|
||||
(set -C; openssl rand -hex 32 > "$target") || exit 1
|
||||
fi
|
||||
done
|
||||
export THT_CATALOG_RUNTIME_PASSWORD_SOURCE="$(pwd -P)/deploy/local/secrets/catalog-runtime-password"
|
||||
export THT_CATALOG_MIGRATOR_PASSWORD_SOURCE="$(pwd -P)/deploy/local/secrets/catalog-migrator-password"</code></pre>
|
||||
<p>Non rigenerare le password di un catalogo già inizializzato. Configurare senza avviare i servizi:</p>
|
||||
<pre class="highlight"><code class="language-sh">tht setup --profile local --shell-mode full --shell-default-locale en --configure-only</code></pre>
|
||||
<p>Rispondere ai prompt nel seguente modo:</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Prompt</th>
|
||||
<th>Valore o regola</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Installation ID</td>
|
||||
<td><code>local</code>, salvo necessità di più installazioni nello stesso clone</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Deployment profile</td>
|
||||
<td><code>local</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DWH API endpoint</td>
|
||||
<td>URL <code>http(s)</code> senza user, password, query o fragment; può restare vuoto per il solo smoke test</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>LLM API endpoint</td>
|
||||
<td>URL <code>http(s)</code> senza credenziali; può restare vuoto per il solo smoke test</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Workspace repository URL</td>
|
||||
<td>URL del repository dei workspace, non il clone sorgente di THothII</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Workspace branch</td>
|
||||
<td>normalmente <code>main</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Workspace access</td>
|
||||
<td><code>ssh</code> se si usa una chiave deploy; altrimenti <code>https</code> con credential file protetto</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Percorsi dei file</td>
|
||||
<td>accettare i percorsi predefiniti sotto <code>deploy/local/secrets/</code> nella prima prova</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Secret templates</td>
|
||||
<td>rispondere <code>yes</code> quando i file protetti non esistono ancora</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Autenticazione</td>
|
||||
<td>configurare il login locale richiesto dall’installazione; non inserire password in una riga di comando</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>La configurazione generata è locale e ignorata da Git:</p>
|
||||
<pre class="highlight"><code class="language-text">deploy/local/thothii-installation.yaml
|
||||
deploy/local/operator.env
|
||||
deploy/local/auth/
|
||||
deploy/local/secrets/</code></pre>
|
||||
<p>Modificare i segreti solo nei file locali protetti; non committarli. Il file <code>deploy/env/local.env.example</code> è un riferimento
|
||||
tracciato; il percorso generato da <code>tht setup</code>, <code>deploy/local/operator.env</code>, è quello da usare per
|
||||
questa installazione.</p>
|
||||
<h3 id="completare-i-file-protetti">Completare i file protetti<a class="headerlink" href="#completare-i-file-protetti" title="Permanent link">¶</a></h3>
|
||||
<p>Se il setup ha creato template vuoti, inserire i valori con un editor locale:</p>
|
||||
<pre class="highlight"><code class="language-sh">chmod 600 deploy/local/secrets/*
|
||||
"${EDITOR:-vi}" deploy/local/secrets/thothii.secrets</code></pre>
|
||||
<p>Il bundle deve contenere solo righe <code>KEY=VALUE</code> per le credenziali effettivamente usate dal
|
||||
<code>modelCatalog</code>. I nomi ammessi e il confine delle credenziali sono descritti nel file locale
|
||||
<code>deploy/secrets/README.md</code>. Non mettere token nelle URL, nel
|
||||
descriptor YAML, nel repository Git o nei comandi copiati nella shell.</p>
|
||||
<p>Per accesso workspace SSH, predisporre anche la chiave privata e il file <code>known_hosts</code> indicati dal
|
||||
setup. Per accesso HTTPS, predisporre il credential file Git e l’eventuale CA. Entrambi devono
|
||||
restare protetti e fuori dal controllo versione.</p>
|
||||
<p>Prima dell'avvio completare anche questi passaggi:</p>
|
||||
<ol>
|
||||
<li>Aggiungere <code>THT_CATALOG_RUNTIME_PASSWORD_SOURCE</code> e <code>THT_CATALOG_MIGRATOR_PASSWORD_SOURCE</code> a
|
||||
<code>deploy/local/operator.env</code>, con gli stessi percorsi assoluti esportati sopra. Il setup non salva
|
||||
queste due variabili. Inserire i percorsi, non le password.</li>
|
||||
<li>Sostituire il <code>modelCatalog</code> generico nel descriptor con la configurazione provider/modelli
|
||||
approvata. I default generati non replicano il Mac esistente. Vedere <a href="../../general/pi-configuration/">configurazione Pi/modelli</a>
|
||||
e l'esempio locale <code>deploy/psd/thothii-installation.yaml.example</code>.</li>
|
||||
<li>Inserire in <code>thothii.secrets</code> le chiavi referenziate da <code>authentication.apiKeyEnv</code>. I provider
|
||||
<code>pi_auth</code> richiedono credenziali valide nel file <code>PI_AUTH_FILE</code>; il template <code>{}</code> non autentica.</li>
|
||||
<li>Completare i file Git del workspace. SSH richiede una chiave deploy autorizzata e known-hosts
|
||||
verificato; HTTPS richiede il credential file e il bundle CA previsti dall'overlay. I template
|
||||
vuoti non consentono l'accesso al repository.</li>
|
||||
</ol>
|
||||
<p>Dopo aver modificato la configurazione generata, non rilanciare setup: rifiuta file esistenti con
|
||||
contenuti diversi. Generare le proiezioni ed eseguire la migrazione esplicita indicata sotto.
|
||||
Impostare <code>THT_GIT_ACCESS=https</code> se scelto nel setup. Il blocco usa il nuovo descriptor <code>local</code>
|
||||
con il solo overlay Git; per installazioni personalizzate includere gli overlay aggiuntivi
|
||||
nello stesso ordine del descriptor.</p>
|
||||
<pre class="highlight"><code class="language-bash">INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
|
||||
tht --installation "$INSTALLATION" installation generate
|
||||
THT_PROJECT="thothii-$(printf '%s' "$INSTALLATION" | shasum -a 256 | cut -c 1-12)"
|
||||
THT_GIT_ACCESS=ssh
|
||||
compose=(
|
||||
docker compose --project-name "$THT_PROJECT" --project-directory "$(pwd -P)"
|
||||
--env-file "$(pwd -P)/deploy/local/operator.env"
|
||||
-f compose.yaml -f deploy/compose.local.yaml
|
||||
-f "deploy/compose.git-$THT_GIT_ACCESS.yaml"
|
||||
-f deploy/local/generated/compose.models.yaml
|
||||
)
|
||||
"${compose[@]}" config --quiet
|
||||
"${compose[@]}" build core frontend
|
||||
"${compose[@]}" up -d catalog-db
|
||||
"${compose[@]}" run --rm catalog-migrate
|
||||
tht --installation "$INSTALLATION" start</code></pre>
|
||||
<p>Fermarsi se un comando fallisce. Il nome progetto coincide con l'hash usato da <code>tht</code>, preservando
|
||||
l'identità dei volumi. <code>catalog-migrate</code> applica le migrazioni Catalog e Memory; <code>tht start</code> non
|
||||
lo esegue automaticamente. Il primo download del modello embedding può richiedere tempo.
|
||||
Usare questa sequenza legata all'installazione, non <code>run-stack.sh</code> con env/progetto diversi.</p>
|
||||
<h2 id="4-verificare-linstallazione">4. Verificare l’installazione<a class="headerlink" href="#4-verificare-linstallazione" title="Permanent link">¶</a></h2>
|
||||
<p>Il descriptor generato per l’ID predefinito è:</p>
|
||||
<pre class="highlight"><code class="language-sh">INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
|
||||
test -f "$INSTALLATION"
|
||||
bash scripts/verify-standalone-install.sh "$INSTALLATION"</code></pre>
|
||||
<p>Il verificatore è read-only: esegue <code>tht doctor --json</code> e <code>tht status</code>, senza ristartare lo stack,
|
||||
rigenerare la configurazione o stampare il contenuto dei segreti.</p>
|
||||
<h3 id="gate-a-smoke-di-piattaforma-su-tutti-e-tre-i-computer">Gate A — smoke di piattaforma, su tutti e tre i computer<a class="headerlink" href="#gate-a-smoke-di-piattaforma-su-tutti-e-tre-i-computer" title="Permanent link">¶</a></h3>
|
||||
<p>Registrare per ogni macchina:</p>
|
||||
<pre class="highlight"><code class="language-sh">uname -a
|
||||
docker version --format '{{.Server.Version}} {{.Server.Arch}}'
|
||||
tht version
|
||||
bash scripts/check-standalone-prerequisites.sh
|
||||
bash scripts/verify-standalone-install.sh "$INSTALLATION"</code></pre>
|
||||
<p>Il gate passa quando il clone è integro, Docker e Compose sono raggiungibili, <code>tht doctor</code> è OK,
|
||||
lo stack è avviato e il frontend risponde sulla porta locale predefinita <code>http://127.0.0.1:8080</code>.
|
||||
Il doctor controlla anche workspace e Pi: registrare separatamente i loro errori senza attribuire
|
||||
ogni fallimento alla piattaforma. Verificare la disponibilità HTTP con:</p>
|
||||
<pre class="highlight"><code class="language-sh">curl --fail --silent --show-error http://127.0.0.1:8080/health</code></pre>
|
||||
<h3 id="gate-b-verifica-funzionale">Gate B — verifica funzionale<a class="headerlink" href="#gate-b-verifica-funzionale" title="Permanent link">¶</a></h3>
|
||||
<p>Eseguire almeno su una macchina con endpoint e credenziali disponibili:</p>
|
||||
<p>Seguire prima <a href="../../operations/workspaces/">Workspace operations</a> per importare/preparare il
|
||||
workspace e configurare Database e binding locale. Il clone sorgente non trasferisce catalogo,
|
||||
segreti o sessioni del Mac. Connettere l'eventuale VPN richiesta da DWH/modelli e verificare
|
||||
che i relativi nomi siano raggiungibili anche dai container.</p>
|
||||
<ol>
|
||||
<li>aprire <code>http://127.0.0.1:8080</code>;</li>
|
||||
<li>autenticarsi con l’account locale configurato;</li>
|
||||
<li>verificare che il workspace configurato sia leggibile;</li>
|
||||
<li>avviare una domanda reale e completare i gate di revisione fino alla SQL finale;</li>
|
||||
<li>fermare e riavviare l’installazione, poi ripetere <code>verify-standalone-install.sh</code>.</li>
|
||||
</ol>
|
||||
<p>Un fallimento del Gate B per DWH, provider LLM, Git workspace o credenziali non dimostra da solo un
|
||||
problema di portabilità Docker: registrare separatamente l’endpoint o il componente fallito.</p>
|
||||
<h2 id="ciclo-di-vita-quotidiano">Ciclo di vita quotidiano<a class="headerlink" href="#ciclo-di-vita-quotidiano" title="Permanent link">¶</a></h2>
|
||||
<p>Usare il descriptor esplicito quando più installazioni possono essere scoperte:</p>
|
||||
<pre class="highlight"><code class="language-sh">INSTALLATION="$PWD/deploy/local/thothii-installation.yaml"
|
||||
|
||||
tht --installation "$INSTALLATION" status
|
||||
tht --installation "$INSTALLATION" start
|
||||
tht --installation "$INSTALLATION" start --build
|
||||
tht --installation "$INSTALLATION" logs
|
||||
tht --installation "$INSTALLATION" doctor --json
|
||||
tht --installation "$INSTALLATION" stop</code></pre>
|
||||
<p><code>start --build</code> è necessario dopo una modifica al codice o per ricostruire le immagini dal clone
|
||||
corrente. <code>stop</code> conserva volumi, sessioni, catalogo, stato Pi, dati Qdrant e modello embedding.
|
||||
Non usare <code>docker compose down --volumes</code> durante una prova normale: è un’operazione distruttiva
|
||||
che cancella i dati locali.
|
||||
Per aggiornamenti che richiedono migrazioni, seguire il runbook della release prima dell'avvio.</p>
|
||||
<h2 id="diagnosi-rapida">Diagnosi rapida<a class="headerlink" href="#diagnosi-rapida" title="Permanent link">¶</a></h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Sintomo</th>
|
||||
<th>Controllo</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>Docker Engine is not reachable</code></td>
|
||||
<td>avviare Docker Desktop oppure il servizio Docker e ripetere <code>docker info</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Windows vede Docker ma Bash fallisce</td>
|
||||
<td>eseguire la guida dentro Ubuntu WSL2 e abilitare l’integrazione della distribuzione in Docker Desktop</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>tht: command not found</code></td>
|
||||
<td>aprire una nuova shell e verificare <code>command -v tht</code>; se necessario ripetere il bootstrap</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>line ending o script non eseguibile</td>
|
||||
<td>usare un clone nel filesystem WSL2/Linux e rieseguire <code>bash scripts/...</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>architettura non supportata</td>
|
||||
<td>verificare <code>docker version --format '{{.Server.Arch}}'</code>; la prova richiede <code>amd64</code> o <code>arm64</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>descriptor o env file mancanti</td>
|
||||
<td>usare il percorso <code>deploy/local/...</code> generato da <code>tht setup</code>, non un file copiato casualmente</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>stack sano ma workflow fallisce</td>
|
||||
<td>controllare separatamente URL, credential bundle, workspace Git e autenticazione</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>dati apparentemente persi</td>
|
||||
<td>verificare che non sia stato usato <code>down --volumes</code>; <code>stop</code> non rimuove i volumi</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h2 id="checklist-di-accettazione">Checklist di accettazione<a class="headerlink" href="#checklist-di-accettazione" title="Permanent link">¶</a></h2>
|
||||
<ul>
|
||||
<li>[ ] Il clone proviene dal repository Gitea atteso e la revisione è stata annotata.</li>
|
||||
<li>[ ] Docker Desktop/Engine e Compose v2 sono disponibili.</li>
|
||||
<li>[ ] Il runtime restituisce un’architettura ammessa.</li>
|
||||
<li>[ ] <code>tht</code> è stato costruito dal repository e risponde a <code>tht version</code>.</li>
|
||||
<li>[ ] Il setup usa <code>profile: local</code>, <code>shell.mode: full</code> e <code>shell.defaultLocale: en</code>.</li>
|
||||
<li>[ ] Descriptor, <code>operator.env</code>, autenticazione e segreti sono presenti solo in <code>deploy/local/</code>.</li>
|
||||
<li>[ ] Nessun segreto compare in Git, URL, YAML pubblico o comandi registrati.</li>
|
||||
<li>[ ] Gate A superato su macOS Apple Silicon, Windows WSL2/x64 e Linux x64.</li>
|
||||
<li>[ ] Gate B eseguito almeno su una macchina con DWH e LLM disponibili.</li>
|
||||
<li>[ ] Stop/start e verifica finale completati senza cancellare i volumi.</li>
|
||||
</ul>
|
||||
<h2 id="fuori-perimetro-di-questa-release">Fuori perimetro di questa release<a class="headerlink" href="#fuori-perimetro-di-questa-release" title="Permanent link">¶</a></h2>
|
||||
<p>Restano attività successive:</p>
|
||||
<ul>
|
||||
<li>pubblicare immagini pre-costruite su Docker Hub;</li>
|
||||
<li>ridurre ulteriormente i prompt tramite una configurazione non interattiva dedicata;</li>
|
||||
<li>creare pacchetti DMG, MSI/EXE, AppImage o altri installer nativi;</li>
|
||||
<li>fornire un runtime offline o un DWH/LLM locale incluso nell’applicazione.</li>
|
||||
</ul>
|
||||
<h2 id="documenti-collegati">Documenti collegati<a class="headerlink" href="#documenti-collegati" title="Permanent link">¶</a></h2>
|
||||
<ul>
|
||||
<li><a href="../first-start/">Install and first start</a></li>
|
||||
<li><a href="../shell-and-language/">Shell and localization</a></li>
|
||||
<li><a href="../../operations/workspaces/">Workspace operations</a></li>
|
||||
<li><code>deploy/secrets/README.md</code> (runtime secrets)</li>
|
||||
</ul>
|
||||
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<div class="row wm-article-nav-buttons" role="navigation" aria-label="navigation">
|
||||
|
||||
<div class="wm-article-nav pull-right">
|
||||
<a href="../standalone-manual-en/" class="btn btn-xs btn-default pull-right">
|
||||
Next
|
||||
<i class="fa fa-chevron-right" aria-hidden="true"></i>
|
||||
</a>
|
||||
<a href="../standalone-manual-en/" class="btn btn-xs btn-link">
|
||||
Mac, Windows, Linux — English
|
||||
</a>
|
||||
</div>
|
||||
|
||||
<div class="wm-article-nav">
|
||||
<a href="../first-start/" class="btn btn-xs btn-default pull-left">
|
||||
<i class="fa fa-chevron-left" aria-hidden="true"></i>
|
||||
Previous</a><a href="../first-start/" class="btn btn-xs btn-link">
|
||||
Start here
|
||||
</a>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<br>
|
||||
</div>
|
||||
|
||||
<footer class="container-fluid wm-page-content">
|
||||
<p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a> using <a href="https://github.com/gristlabs/mkdocs-windmill">Windmill</a> theme by Grist Labs.</p>
|
||||
</footer>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user