3.0 KiB
Install and first start
Use the guided procedure for a fresh installation:
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.