177 lines
9.1 KiB
Markdown
177 lines
9.1 KiB
Markdown
# Local workspace repository installation (macOS, Windows, and Linux)
|
|
|
|
This manual connects a local ThothII installation to one remote Git repository hosted by a Git
|
|
server such as GitHub, GitLab, or Gitea. ThothII is a read-only consumer: it fetches,
|
|
validates, and activates workspace revisions, but never edits, commits, pushes, or publishes them.
|
|
|
|
## Architecture ownership contract
|
|
|
|
| Component | Ownership | Operator contract |
|
|
| --- | --- | --- |
|
|
| DWH | External | Configure the external endpoint and complete its runtime credentials in Workspace management. |
|
|
| LLM | External | Configure the external endpoint and model policy during installation. |
|
|
| Qdrant | Internal | Compose runs the internal service and persists `qdrant-data`. |
|
|
| Ollama embedding | Internal | Compose runs the internal `qwen3-embedding:0.6b` service and model-init job. |
|
|
|
|
## Semantic index ownership contract
|
|
|
|
| Scope | Ownership rule | Isolation rule |
|
|
| --- | --- | --- |
|
|
| Workspace semantic index | Each workspace keeps exactly one Qdrant collection reserved for itself. | Schema, Evidence, and memory records share that one collection and are separated by the `kind` payload. |
|
|
|
|
The mandatory semantic stack is CPU-first. Set `THOTH_ENABLE_EMBEDDING_GPU=1` only after the
|
|
documented GPU prerequisites are satisfied. The embedding contract is fixed at
|
|
`qwen3-embedding:0.6b`, 1024 dimensions, cosine distance.
|
|
|
|
## Prerequisites
|
|
|
|
- A working local installation described by [local.md](local.md).
|
|
- A remote Git repository and a read-only deploy credential for this ThothII installation.
|
|
- A separate authoring clone in which a workspace curator can edit and publish source revisions.
|
|
- `tht` built with `bash scripts/build-tht.sh`.
|
|
|
|
## Prepare and publish a workspace source
|
|
|
|
Create a local workspace in an ordinary source directory outside ThothII's data directories. The
|
|
canonical repository layout is:
|
|
|
|
```text
|
|
thoth-workspaces.yaml
|
|
<workspace-id>/workspace.yaml
|
|
<workspace-id>/evidence/ # optional, repository-owned Evidence
|
|
<workspace-id>/schema/annotations.yaml # optional curated annotations
|
|
```
|
|
|
|
The catalog lists `{id, name, description?}` and the descriptor at
|
|
`<workspace-id>/workspace.yaml` must match that metadata. Use the examples in
|
|
`deploy/workspaces/` as authoring references. Do not store passwords, tokens, private keys, or
|
|
signed URLs in Git.
|
|
|
|
Publishing is an author-side Git operation: validate the source, commit it, and push it from the
|
|
separate authoring clone to the configured branch. This is the only meaning of “publish” in the
|
|
workspace lifecycle. ThothII has no author identity and no Git write credential.
|
|
|
|
## Use the workspace from the application
|
|
|
|
After the installation is started, use Workspace management from the authenticated application:
|
|
|
|
1. Run **Update workspace repository** to fetch and validate the configured Git branch into the
|
|
application-owned registry. The operation is all-or-nothing and does not modify the authoring
|
|
clone.
|
|
2. Confirm that the installation-owned `workspace-secrets` storage remains outside the source
|
|
repository and contains no credentials in the workspace descriptors.
|
|
3. Select the workspace and run **Validate workspace source** to verify the active descriptor, catalog,
|
|
Evidence, annotations, and runtime bindings.
|
|
4. Run **Test workspace connections** only with the approved read-only DWH/Evidence test configuration.
|
|
Results are redacted and the workspace source remains unchanged.
|
|
|
|
<!-- workspace-descriptor-contract:start -->
|
|
Schema v3 is the only accepted workspace descriptor.
|
|
Schema v1 and v2 workspace descriptors are rejected before activation.
|
|
<!-- workspace-descriptor-contract:end -->
|
|
|
|
## Configure the remote Git repository
|
|
|
|
Copy `docs/install/examples/thothii-installation.local.yaml` to an operator-controlled absolute
|
|
path. Its `workspaceRepository` block records the remote, branch, and read-only access method.
|
|
Choose exactly one transport override:
|
|
|
|
- SSH: `deploy/compose.git-ssh.yaml`, with a read-only deploy key and pinned `known_hosts` file.
|
|
- HTTPS: `deploy/compose.git-https.yaml`, with a read-only token in a Git credentials file and an
|
|
optional private CA file.
|
|
|
|
The remote and branch are installation configuration. Git credentials remain protected
|
|
installation files and are never accepted by Workspace management or returned by its API.
|
|
|
|
Example non-secret/operator paths:
|
|
|
|
```dotenv
|
|
THT_WORKSPACE_GIT_REMOTE=git@git.example.com:organization/workspaces.git
|
|
THT_WORKSPACE_GIT_BRANCH=main
|
|
THT_WORKSPACE_INSTALLATION_ID=local
|
|
PI_AUTH_FILE=/absolute/path/to/operator/pi-auth.json
|
|
THT_SECRETS_FILE=/absolute/path/to/operator/thothii.secrets
|
|
THT_WORKSPACE_GIT_SSH_KEY_FILE=/absolute/path/to/operator/git-ssh-key
|
|
THT_WORKSPACE_GIT_KNOWN_HOSTS_FILE=/absolute/path/to/operator/git-known-hosts
|
|
```
|
|
|
|
Keep these files outside both the ThothII checkout and the workspace source repository. Protect
|
|
them with mode `0600` on macOS/Linux or an equivalent single-user ACL on Windows.
|
|
|
|
## Start and update the installation
|
|
|
|
Use only the installation-aware lifecycle:
|
|
|
|
```bash
|
|
export THT_SOURCE_ROOT=/absolute/path/to/ThothII
|
|
THT_BIN=tht
|
|
INSTALLATION=/absolute/path/to/operator/thothii-installation.yaml
|
|
"$THT_BIN" --installation "$INSTALLATION" start
|
|
"$THT_BIN" --installation "$INSTALLATION" doctor
|
|
```
|
|
|
|
At startup ThothII clones or fetches the configured repository into its application-managed
|
|
`workspace-registry` volume. Later, **Update workspace repository** performs a server-side fetch
|
|
and fast-forward candidate checkout. It does not copy anything to the user's computer.
|
|
|
|
## Complete runtime secrets in Workspace management
|
|
|
|
### Chiavi DWH REST per installazione
|
|
|
|
Se il binding selezionato è `rest_api`, la chiave DWH è una credenziale per questa installazione e si salva nel vault tramite **Save entered secrets** oppure in un file locale indicato da `API_KEY_FILE`. `postgres_direct` e `ssh_tunnel` non usano questa chiave. Per emissione, TLS, rotazione e verifica `/rpc/ping`, seguire [enrollment DWH REST](dwh-auth-client-enrollment.md).
|
|
|
|
Open Workspace management after the first successful repository update.
|
|
|
|
1. At the repository level, review the configured host, repository, branch, and current revision.
|
|
2. Select a workspace. Repository update does not require a selection; validation and connection
|
|
tests do.
|
|
3. Review the runtime fields derived from the selected DWH transport and Evidence authentication
|
|
mechanism.
|
|
4. Enter or rotate the required values and choose **Save entered secrets**.
|
|
5. Run **Validate workspace source** and then **Test workspace connections**.
|
|
|
|
Secret fields are write-only. The GUI receives only configured/missing status. Values are
|
|
encrypted by the backend in the platform-neutral `workspace-secrets` volume. ThothII temporarily
|
|
materializes a restrictive file only while an existing file-oriented connector needs it, then
|
|
removes that file when the runtime lease ends. **Forget stored value** deletes the selected encrypted value.
|
|
|
|
The workspace YAML stays environment-independent: it declares connector mechanisms, not host
|
|
paths or credentials. Installation trust material such as a Git CA or `known_hosts` remains an
|
|
operator concern; DWH and Evidence credentials are completed in the GUI.
|
|
|
|
## Validation and activation behavior
|
|
|
|
An update follows this sequence:
|
|
|
|
1. Fetch the configured branch into a candidate checkout managed by ThothII.
|
|
2. Validate the catalog, every descriptor, repository-relative Evidence, and cross-workspace
|
|
invariants at the same Git commit.
|
|
3. If every workspace is valid, atomically mark that complete commit as active.
|
|
4. If any validation fails, report sanitized diagnostics and keep the previous active revision.
|
|
|
|
The active checkout is read-only application state. Never edit files under
|
|
`/data/workspace-registry`. A source correction must be committed and pushed from the authoring
|
|
clone, then fetched again with **Update workspace repository**.
|
|
|
|
## Backup, rotation, and recovery
|
|
|
|
Back up the `workspace-registry`, `workspace-secrets`, `sessions`, `qdrant-data`,
|
|
`embedding-models`, `settings`, and `pi-state` volumes together. The encrypted vault is useless
|
|
without its generated master key, so preserve the entire `workspace-secrets` volume and protect
|
|
the backup as secret material.
|
|
|
|
Rotate a runtime credential by saving its replacement in Workspace management and rerunning its
|
|
connection test. Rotate Git credentials in the installation files and restart `core`. To recover
|
|
from a bad remote revision, correct or revert it in the authoring repository and run the update;
|
|
until validation succeeds, the previous active snapshot remains available.
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Meaning and action |
|
|
| --- | --- |
|
|
| Repository unavailable | Check remote host, branch, read-only deploy credential, CA, and `known_hosts`. |
|
|
| Candidate rejected | Fix the reported source error in the authoring clone, commit, push, and update again. |
|
|
| Runtime configuration required | Select the workspace and complete each required secret field. |
|
|
| Connection test fails | Rotate the relevant secret or correct the non-secret endpoint in the source/installation as appropriate. |
|
|
| Active revision did not change | The candidate was invalid or was already active; inspect the repository status. |
|