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

docs: separate public manual from internal project documentation
Publish documentation / publish (push) Successful in 27s
Details

Browse Source
This commit is contained in:
Codex
2026-09-15 10:26:35 +02:00
parent 6a4634dcf1
commit 043ffdfad6
26 changed files with 859 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/install/authentication-local.md
+1 -1
View File
@@ -3,7 +3,7 @@
Use local mode for a standalone PC or Mac, with `shell.mode: full` and
`shell.defaultLocale: en` in the installation descriptor. Presentation and
authentication are independent: selecting full does not create accounts. Omics
embedded instead uses the [upstream guide](authentication-upstream.md), not local users.
embedded instead uses the [upstream guide](shell-and-language.md), not local users.
Configure local authentication through `tht`; passwords are entered at an
echo-free prompt or read from a protected `--password-file`, never from a command argument.
docs/install/authentication-oidc.md
+3 -3
View File
@@ -2,7 +2,7 @@
Use this guide for **ThothII's own login**, normally `shell.mode: full` on an
autonomous server. It is not the integration procedure for an already logged-in
Omics user. That deployment uses [embedded/upstream](authentication-upstream.md),
Omics user. That deployment uses [embedded/upstream](shell-and-language.md),
even when Omics's identity provider is Authentik.
OIDC mode supports a standards-based provider. The browser flow is generic: Authorization Code,
@@ -104,7 +104,7 @@ Any authentication failure prevents activation according to the static or live s
relevant diagnostic surface.
The complete closed diagnostic-code union and exact role-to-permission expansion are in the
[authentication architecture](../architecture/authentication.md).
[authentication architecture](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/architecture/authentication.md).
## Browser login and logout
@@ -114,4 +114,4 @@ 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 [manual acceptance matrix](../testing/authentication-manual-acceptance.md).
storage. See the [manual acceptance matrix](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/testing/authentication-manual-acceptance.md).
docs/install/authentik.md
+1 -1
View File
@@ -8,7 +8,7 @@ For **embedded in Omics**, retain Omics's existing Authentik authentication and
configure ThothII as upstream. Omics verifies `datamart_builder.access` 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
[portal integration guide](authentication-upstream.md).
[portal integration guide](shell-and-language.md).
```mermaid
sequenceDiagram
docs/install/first-start.md
+47 -81
View File
@@ -1,98 +1,64 @@
# Install and first start
For the ordered clone-to-start procedure on Mac, Windows WSL2 and Linux, use the
[Italian manual guide](standalone-manual-it.md) or [English manual guide](standalone-manual-en.md),
including protected credentials and the explicit initial catalog migration.
Use one complete procedure for a fresh installation:
This is the supported local installation path. It creates an installation-local configuration and
starts the Compose stack; it does not create a workspace repository or a database catalog entry.
- [Italian manual installation](standalone-manual-it.md)
- [English manual installation](standalone-manual-en.md)
## Prerequisites and boundaries
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.
Install Docker Engine with Compose v2, plus the host `tht` command. On macOS or Linux, install the
host command from the repository with `./scripts/install-tht.sh`; Windows uses
`./scripts/install-tht.ps1`. The installer builds or verifies the native command and checks that
`tht` is resolvable on `PATH`.
## What must be ready
The stack contains `frontend`, `core`, `catalog-db`, `qdrant`, `embedding`, and the one-shot
`embedding-model-init` and `catalog-migrate` services. DWH and model-provider endpoints are
external installation settings. Pi runs inside `core`; do not install a host Pi executable for
the application runtime.
You need Docker with Compose, the host operator command `tht`, 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.
Secrets, certificates, Pi authentication, and workspace endpoint bindings are protected
installation-local files. Never put them in a workspace descriptor, an env file intended for
version control, a URL, or a command line.
The stack includes `frontend`, `core`, `catalog-db`, `qdrant`, `embedding`, plus the
one-shot `embedding-model-init` and `catalog-migrate` services. DWH and generative-model
endpoints remain separate installation settings.
## Create the local installation
Secrets, certificates, Pi authentication and endpoint bindings are protected local files.
Do not commit them or copy the configuration of another machine unchanged.
From the repository root, start the interactive setup and select the local profile:
## Follow the ordered procedure
The bilingual guides provide the exact commands for:
1. Cloning the selected revision and checking prerequisites.
2. Bootstrapping the native host command.
3. Preparing catalog passwords and using
`tht setup --profile local --shell-mode full --shell-default-locale en --configure-only`.
4. Completing model, authentication and workspace credentials.
5. Generating configuration, building images and explicitly running `catalog-migrate`.
6. Starting the installation and checking health and readiness.
Do not run setup alone as a substitute for that sequence. Migrations are not an
implicit effect of backend startup or `tht start`. Do not mix this installation's
descriptor/project with a different low-level Compose environment.
For an already configured installation:
```sh
tht setup --profile local --shell-mode full --shell-default-locale en
```
It writes the selected non-secret descriptor below `deploy/<installation-id>/`, the associated
operator env file, and can create protected secret templates. Keep the descriptor path: pass it
to commands as `--installation /absolute/path/thothii-installation.yaml` when more than one
installation can be discovered.
The explicit shell options are important: compatibility defaults without them
are embedded/en/omics-portal, which expects an Omics document. The Mac's standalone
installation must use full, with English as its initial locale. Existing browser
language preferences take precedence over that initial value. Full does not
configure authentication; setup separately bootstraps local login.
For a server portal, use the [embedded/upstream procedure](authentication-upstream.md)
instead of creating a second ThothII login. For a standalone server, use full
with [direct OIDC](authentication-oidc.md). Shell mode does not follow `profile`
automatically. See [configuration and regeneration](../operations/shell-and-localization.md)
before modifying an existing installation.
If the descriptor is prepared manually instead, begin with
[`thothii-installation.local.yaml`](examples/thothii-installation.local.yaml), set mode `0600` or
`0400`, and ensure `THT_INSTALLATION_CONFIG_SOURCE` in the selected env file points to that exact
file. Create the secret bundle from `deploy/secrets/thothii.secrets.example`, protect it, and set
the file locations and external endpoints in the env file. The required settings include:
- `PI_AUTH_FILE`, `THT_SECRETS_FILE`, and the catalog password source files;
- `THT_INSTALLATION_CONFIG_SOURCE` and the workspace Git remote/branch;
- the DWH and model-provider endpoints; and
- `THT_AUTH_CONFIG_ROOT` for local authentication or the OIDC configuration selected during setup.
For the supported secret names and the metadata-generation model credential boundary, see the
`deploy/secrets/README.md` file in the installation checkout. It is intentionally not published
as a documentation page because it describes a protected local-file contract.
## Start and verify
For the normal local path, use the launcher:
```sh
./scripts/run-stack.sh
```
It builds `core`, starts `catalog-db`, runs `catalog-migrate`, then keeps the base plus local
Compose profile in the foreground. Database migrations are deliberately not a hidden backend
startup action. Open `http://127.0.0.1:8080` unless `THOTH_HTTP_PORT` was changed.
In another terminal, verify the installation without changing it:
```sh
tht --installation /absolute/path/thothii-installation.yaml doctor --json
tht --installation /absolute/path/thothii-installation.yaml status
tht --installation /absolute/path/thothii-installation.yaml doctor --json
```
`/health` verifies application-process readiness; `tht doctor` is the diagnostic surface for
Compose, configuration, workspace, workflow, and Pi prerequisites.
`/health` 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.
## Routine lifecycle and next steps
## After startup
Use `tht start [--build]`, `tht stop`, `tht logs`, and `tht doctor` rather than composing ad-hoc
container commands. Named volumes retain settings, Pi state, workspace registry, sessions,
Qdrant data, and embedding models across `docker compose down`; removing them requires the
explicit destructive `--volumes` form.
Prepare [workspaces](../operations/workspaces.md), configure a database in
[Database Management](../operations/database-management.md), and complete the functional
checks in the installation guide before using real data.
After the stack is healthy, configure authentication if setup did not do so, then continue with
[Workspace operations](../operations/workspaces.md). For server profile, reverse proxy, backups,
and recovery, use the deployment program and its manual gates; the server profile is not a
drop-in replacement for the local command above.
See [display mode and language](shell-and-language.md), [local authentication](authentication-local.md),
[OIDC](authentication-oidc.md) and [model configuration](../general/pi-configuration.md)
for later changes. Embedded portal integration is separate from a fresh standalone setup.
Use the installation's normal `tht start`, `tht stop` and diagnostic commands.
Preserve its descriptor, credentials, database and persistent volumes; do not use
`down --volumes` as a routine stop or upgrade.
docs/install/shell-and-language.md
+70
View File
@@ -0,0 +1,70 @@
# Display mode and language
ThothII can run with its own application header (**full**) or inside an integrated
portal (**embedded**). Display mode and authentication are separate choices.
| Installation | Display | Authentication |
| --- | --- | --- |
| Standalone local instance | `full` | Local ThothII account |
| Standalone server | `full` | Local accounts or configured OIDC provider |
| Integrated portal | `embedded` | Identity verified by the portal's trusted server proxy |
## Standalone setup
Follow the complete [Italian](standalone-manual-it.md) or
[English](standalone-manual-en.md) installation procedure. It explicitly selects
`--shell-mode full --shell-default-locale en` and separates configuration, credentials,
initial migrations and startup. Do not skip those steps by running setup alone.
The authored installation descriptor contains:
```yaml
shell:
mode: full
defaultLocale: en
```
Use `it` for an Italian initial interface. Existing browser language preferences can
override that initial value. Full mode remembers language and theme in the browser.
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 `tht` binary:
```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
```
Generation updates derived configuration; it does not start services. `start` 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.
## Authentication and embedded deployments
Full mode does not configure login by itself. See [local authentication](authentication-local.md)
or [OIDC](authentication-oidc.md), with [Authentik](authentik.md) as a provider option.
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.
Portal implementation details belong to the
[developer integration reference in the repository](https://git.tylconsulting.it/mptyl/ThothII/src/branch/main/docs/install/authentication-upstream.md),
not to the standalone installation procedure.
## Three different languages
- **Interface language** controls labels, forms and application messages.
- **Session interaction language** is captured when a session is created. Resuming it
retains that language even if the interface language changes later.
- **Workspace language** concerns domain content and retrieval; switching the interface
does not translate Evidence, SQL, identifiers or database values.
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.
docs/install/standalone-manual-en.md
+1 -1
View File
@@ -319,6 +319,6 @@ The following remain future work:
## Related documents
- [Install and first start](first-start.md)
- [Shell and localization](../operations/shell-and-localization.md)
- [Shell and localization](shell-and-language.md)
- [Workspace operations](../operations/workspaces.md)
- `deploy/secrets/README.md` (runtime secrets)
docs/install/standalone-manual-it.md
+1 -1
View File
@@ -324,6 +324,6 @@ Restano attività successive:
## Documenti collegati
- [Install and first start](first-start.md)
- [Shell and localization](../operations/shell-and-localization.md)
- [Shell and localization](shell-and-language.md)
- [Workspace operations](../operations/workspaces.md)
- `deploy/secrets/README.md` (runtime secrets)