83 lines
3.9 KiB
Markdown
83 lines
3.9 KiB
Markdown
# 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.
|