# Install and first start

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:

```sh
tht setup --profile local
```

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.

If the descriptor is prepared manually instead, begin with
[`thothii-installation.local.yaml`](examples/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:

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

```sh
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](../operations/workspaces.md). 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.