64 lines
3.0 KiB
Markdown
64 lines
3.0 KiB
Markdown
# Install and first start
|
||
|
||
Use the guided procedure for a fresh installation:
|
||
|
||
- [Italian guided installation](standalone-manual-it.md)
|
||
- [English guided installation](standalone-manual-en.md)
|
||
|
||
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 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 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.
|
||
|
||
## One guided command
|
||
|
||
After cloning THothII, checking prerequisites and installing tht, run:
|
||
|
||
~~~
|
||
tht setup --complete --profile local --shell-mode full --shell-default-locale en
|
||
~~~
|
||
|
||
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:
|
||
|
||
~~~
|
||
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
|
||
~~~
|
||
|
||
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.
|
||
|
||
## Installer-only completion
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
See the guides for the Windows/macOS/Linux prerequisite matrix, workspace repository explanation,
|
||
secret layout and Gate A/Gate B acceptance checks.
|