ThothII/docs/install/first-start.md

Install and first start

For the ordered clone-to-start procedure on Mac, Windows WSL2 and Linux, use the Italian manual guide or English manual guide, including protected credentials and the explicit initial catalog migration.

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.

Prerequisites and boundaries

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.

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.

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.

Create the local installation

From the repository root, start the interactive setup and select the local profile:

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 instead of creating a second ThothII login. For a standalone server, use full with direct OIDC. Shell mode does not follow profile automatically. See configuration and regeneration before modifying an existing installation.

If the descriptor is prepared manually instead, begin with 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:

./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:

tht --installation /absolute/path/thothii-installation.yaml doctor --json
tht --installation /absolute/path/thothii-installation.yaml status

/health verifies application-process readiness; tht doctor is the diagnostic surface for Compose, configuration, workspace, workflow, and Pi prerequisites.

Routine lifecycle and next steps

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.

After the stack is healthy, configure authentication if setup did not do so, then continue with Workspace operations. 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.