Install and first start

Use one complete procedure for a fresh installation:

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.

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.

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.

Secrets, certificates, Pi authentication and endpoint bindings are protected local files. Do not commit them or copy the configuration of another machine unchanged.

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:

tht --installation /absolute/path/thothii-installation.yaml status
tht --installation /absolute/path/thothii-installation.yaml doctor --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.

After startup

Prepare workspaces, configure a database in Database Management, and complete the functional checks in the installation guide before using real data.

See display mode and language, local authentication, OIDC and model configuration 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.