wip: guided standalone installation and workspace checks
This commit is contained in:
Codex
+41
-42
@@ -1,64 +1,63 @@
|
||||
# Install and first start
|
||||
|
||||
Use one complete procedure for a fresh installation:
|
||||
Use the guided procedure for a fresh installation:
|
||||
|
||||
- [Italian manual installation](standalone-manual-it.md)
|
||||
- [English manual installation](standalone-manual-en.md)
|
||||
- [Italian guided installation](standalone-manual-it.md)
|
||||
- [English guided installation](standalone-manual-en.md)
|
||||
|
||||
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.
|
||||
The procedure covers Windows through Ubuntu WSL2, macOS, and Linux including an Omarchy/Arch-like
|
||||
host. It uses the application clone, one installation secret bundle, protected repository
|
||||
credentials when needed, and a terminal command. No host Node.js, Python or Pi installation is
|
||||
required.
|
||||
|
||||
## What must be ready
|
||||
|
||||
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.
|
||||
You need Docker with Compose v2, Git, Bash, curl, OpenSSL and shasum. You also need access to the
|
||||
workspace repository and the values supplied by its owner: repository URL/branch, DWH endpoint,
|
||||
database/schema, transport, credentials or certificates, Evidence credentials when applicable,
|
||||
and LLM provider/API-key information.
|
||||
|
||||
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.
|
||||
The workspace repository and the THothII application repository are different. A workspace
|
||||
descriptor may declare Evidence, but database passwords and installation bindings are stored in
|
||||
the installation Catalog, not in Git.
|
||||
|
||||
Secrets, certificates, Pi authentication and endpoint bindings are protected local files.
|
||||
Do not commit them or copy the configuration of another machine unchanged.
|
||||
## One guided command
|
||||
|
||||
## Follow the ordered procedure
|
||||
After cloning THothII, checking prerequisites and installing tht, run:
|
||||
|
||||
The bilingual guides provide the exact commands for:
|
||||
~~~
|
||||
tht setup --complete --profile local --shell-mode full --shell-default-locale en
|
||||
~~~
|
||||
|
||||
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.
|
||||
The first run creates protected placeholders under deploy/local/secrets/. Fill the required
|
||||
credential files and rerun the same command. The command validates the local files and paths,
|
||||
renders Compose, builds the images, starts catalog-db, runs catalog-migrate, starts the full
|
||||
stack, and pulls/activates the workspace repository. Evidence source files declared by the
|
||||
workspace are imported during activation.
|
||||
|
||||
For an already configured installation:
|
||||
|
||||
```sh
|
||||
~~~
|
||||
tht --installation /absolute/path/thothii-installation.yaml status
|
||||
tht --installation /absolute/path/thothii-installation.yaml doctor --json
|
||||
```
|
||||
tht --installation /absolute/path/thothii-installation.yaml workspace test --json
|
||||
~~~
|
||||
|
||||
`/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.
|
||||
doctor --json is the non-destructive general core test. workspace test also probes the configured
|
||||
database, Evidence, Qdrant and embedding service for every active workspace. It requires the
|
||||
workspace database to have been configured in Database Management first.
|
||||
|
||||
## After startup
|
||||
## Installer-only completion
|
||||
|
||||
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.
|
||||
The installer must still decide which LLMs and API keys are approved, configure and test each
|
||||
workspace database, synchronize its schema, generate and consolidate descriptions, create Qdrant
|
||||
entries, review naming-based FK suggestions alongside schema FKs, and load the approved
|
||||
relationships. The final declaration of completeness requires green doctor and workspace test
|
||||
results plus one real natural-language question completed through final SQL.
|
||||
|
||||
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.
|
||||
Migrations are part of setup --complete. Do not mix this installation’s descriptor or volumes with
|
||||
a different Compose environment. Preserve the descriptor, credentials, Catalog and persistent
|
||||
volumes; do not use docker compose down --volumes as a routine stop.
|
||||
|
||||
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.
|
||||
See the guides for the Windows/macOS/Linux prerequisite matrix, workspace repository explanation,
|
||||
secret layout and Gate A/Gate B acceptance checks.
|
||||
|
||||
Reference in New Issue
Block a user