# Install and first start

Use one complete procedure for a fresh installation:

- [Italian manual installation](standalone-manual-it.md)
- [English manual installation](standalone-manual-en.md)

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:

```sh
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](../operations/workspaces.md), configure a database in
[Database Management](../operations/database-management.md), and complete the functional
checks in the installation guide before using real data.

See [display mode and language](shell-and-language.md), [local authentication](authentication-local.md),
[OIDC](authentication-oidc.md) and [model configuration](../general/pi-configuration.md)
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.