# Install and first start

For the ordered clone-to-start procedure on Mac, Windows WSL2 and Linux, use the
[Italian manual guide](standalone-manual-it.md) or [English manual guide](standalone-manual-en.md),
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:

```sh
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](authentication-upstream.md)
instead of creating a second ThothII login. For a standalone server, use full
with [direct OIDC](authentication-oidc.md). Shell mode does not follow `profile`
automatically. See [configuration and regeneration](../operations/shell-and-localization.md)
before modifying an existing installation.

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.