feat(cli): prepare and validate application documents offline

2026-09-28 16:33:07 +02:00
parent 64e6b9664a
commit b9c3369e7b
20 changed files with 1164 additions and 49 deletions
@@ -64,6 +64,94 @@ success does not certify semantic truth, connectivity or readiness. The Git revi
 activated later must contain the checked documents; this command does not publish
 uncommitted files or empty directories.

+## Prepare and validate application documents
+
+After validating workspaces, create a local directory **outside their repository**:
+
+```sh
+tht installation prepare --directory ./my-installation
+```
+
+This creates private, commented `thothii-installation.yaml`, `operator.env`,
+`database-bootstrap.yaml` and `README.md`. The destination must be new and its parent
+must exist. It starts no services and does not implicitly generate passwords.
+
+1. Choose models and providers in the descriptor. The template proposes
+   `openai/gpt-4.1-mini` for interaction and `ollama/qwen3-embedding:0.6b` with 1024
+   dimensions for embedding. Edit these before setup. `modelCatalog.defaults.interaction`
+   must support sessions and metadata generation when the latter is configured.
+   The template omits optional metadata generation. See
+   [model configuration](../general/pi-configuration.md) for custom providers.
+2. Replace the Git remote in both the descriptor and `operator.env`; keep branch and
+   transport consistent. Paths are absolute and machine-local. `operator.env` accepts
+   one literal `KEY=value` assignment per line, without duplicate keys or shell
+   interpolation. Credentials belong in referenced protected files.
+3. Complete `database-bootstrap.yaml` with exactly one entry per workspace. A complete
+   direct-connection example is:
+
+   ```yaml
+   schemaVersion: 1
+   databases:
+     - workspaceId: practice
+       engine: postgres
+       databaseName: sales
+       schema: public
+       binding:
+         transport: postgres_direct
+         host: db.intranet
+         port: 5432
+         username: thoth_reader
+       secretFiles:
+         password: /private/path/my-installation/secrets/database-password
+   ```
+
+   Use a read-only DWH account. `rest_api` requires `baseUrl`, `restPath`, `restAuth`
+   (`none`, `bearer`, `x-api-key`) and `secretFiles.apiKey` when authenticated.
+   `ssh_tunnel` requires `username`, `sshHost`, `sshPort`, `sshUsername`,
+   `sshTargetHost`, `sshTargetPort` and files `password`, `sshPrivateKey`,
+   `sshKnownHosts`; it supports Catalog diagnostics, not NL-to-SQL sessions.
+   `tlsCa` and `sshPrivateKeyPassphrase` are optional. Signed HTTP Evidence needs
+   `evidenceSecretFiles` with key `evidence.signed_urls`; static S3 credentials need
+   `evidence.access_key`, `evidence.secret_key` and optional `evidence.session_token`.
+   All values are private file paths. Workspace descriptors remain schema v4;
+   this bootstrap input is not a second runtime Catalog.
+4. Explicitly generate technical credentials in the standard layout:
+
+   ```sh
+   tht installation credentials --directory ./my-installation
+   ```
+
+   This creates separate random Catalog runtime/migrator and administrator passwords,
+   `auth/auth.yaml`, `auth/users.yaml`, a `secrets/secrets.env` template and
+   `secrets/pi-auth.json`. Existing files are retained; invalid ones stop the command.
+   The initial administrator is `admin`; its password stays in private
+   `secrets/admin-password` and is never printed. The default is local authentication
+   at `http://localhost:8080`: review and edit `auth/auth.yaml` before validation.
+   This increment does not validate offline OIDC bootstrap for the existing path.
+5. Fill the provider key in `secrets/secrets.env` and create the DWH password file.
+   For Git HTTPS supply the referenced credentials and CA files; empty credentials
+   are allowed for a public remote, and the CA file must be available. For SSH supply
+   a key and known_hosts and select the matching descriptor override. `pi_auth`
+   providers require prepared Pi credentials. Keep every secret outside workspace
+   Git with installer-only access (0600 on Unix, equivalent Windows ACLs).
+6. Validate and repeat after each correction:
+
+   ```sh
+   tht --installation /absolute/path/my-installation/thothii-installation.yaml installation validate --workspaces /absolute/path/my-workspaces --json
+   ```
+
+   The default bootstrap is beside the descriptor; `--bootstrap PATH` selects another.
+   Validation changes no documents, generates no projections, uses no network and
+   writes no database. It rejects placeholders, inconsistencies, missing/non-private
+   files and secrets inside workspace Git. Reports identify document, field and
+   correction without secret values. Exit statuses: 0 local success, 1 corrections
+   needed, 2 invalid arguments.
+
+Standard release Compose assets may still be absent at this stage; custom overrides
+must already exist. Release assets, external connectivity, Catalog import and runtime
+readiness remain explicit deferred checks. Success prepares the next preflight;
+it neither skips those checks nor establishes a completed installation.
+
 ## Before you start: the two repositories

 There are two separate repositories: