docs: reorganize operational documentation

2026-08-29 20:08:48 +02:00
parent d504b1def1
commit 0ce05869cf
10 changed files with 371 additions and 337 deletions
@@ -0,0 +1,82 @@
+# 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.