129 lines
6.7 KiB
Markdown
129 lines
6.7 KiB
Markdown
# Server workspace repository installation
|
|
|
|
This manual supplements [server.md](server.md). A server installation reads one remote Git
|
|
repository hosted by GitHub, GitLab, Gitea, Bitbucket, or another Git server. ThothII fetches and
|
|
validates complete revisions but never edits, commits, pushes, or publishes workspace source.
|
|
|
|
## Architecture ownership contract
|
|
|
|
| Component | Ownership | Operator contract |
|
|
| --- | --- | --- |
|
|
| DWH | External | Configure the external endpoint and complete runtime credentials through the authenticated GUI. |
|
|
| LLM | External | Configure the external endpoint and model policy under installation control. |
|
|
| Qdrant | Internal | Compose runs private Qdrant and persists `qdrant-data`; include it in Qdrant backup/restore. |
|
|
| Ollama embedding | Internal | Compose runs private Ollama with `qwen3-embedding:0.6b`. |
|
|
|
|
## 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 fixed semantic contract is 1024 dimensions and cosine distance. DWH and LLM remain external;
|
|
Qdrant, Ollama, and `embedding-model-init` remain private internal services.
|
|
|
|
## Service account, storage, and firewall
|
|
|
|
Run the application as the documented unprivileged service account. Keep the source checkout,
|
|
operator files, application data, and workspace authoring clone separate:
|
|
|
|
```text
|
|
/srv/thothii/app/ # ThothII source release
|
|
/srv/thothii/operator/ # installation descriptor and protected Git files
|
|
/srv/thothii/data/ # application data, encrypted workspace vault, sessions
|
|
/srv/workspace-authoring/ # optional curator clone; never mounted into ThothII
|
|
```
|
|
|
|
Expose only the authenticated same-origin reverse proxy. Keep `core`, Qdrant, and Ollama private.
|
|
|
|
## Prepare and publish a workspace source
|
|
|
|
Create a local workspace in the external authoring repository, which contains
|
|
`thoth-workspaces.yaml`, one
|
|
`<workspace-id>/workspace.yaml` per catalog entry, optional repository-owned Evidence, and optional
|
|
curated schema annotations. It contains no credentials.
|
|
|
|
Publishing belongs to the curator workflow outside ThothII: validate, review, commit, and push the
|
|
source revision to the configured protected branch. Grant the ThothII service only read access.
|
|
|
|
<!-- 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.server.yaml` to
|
|
`/srv/thothii/operator/thothii-installation.yaml`. Set `workspaceRepository.remote`, `.branch`, and
|
|
`.access`, then select exactly one Git transport override. The remote and credential are normally
|
|
repository-scoped read-only deploy credentials.
|
|
|
|
For SSH, mount a private key and pinned known-hosts file. For HTTPS, mount a Git credentials file
|
|
and the required CA chain. These installation credentials are not editable in Workspace
|
|
management and are never exposed by the API.
|
|
|
|
## Start and update the installation
|
|
|
|
Use the installation-aware controller described by `server.md`:
|
|
|
|
```bash
|
|
THTCTL=/srv/thothii/operator/thothctl
|
|
INSTALLATION=/srv/thothii/operator/thothii-installation.yaml
|
|
"$THTCTL" --installation "$INSTALLATION" start
|
|
"$THTCTL" --installation "$INSTALLATION" doctor
|
|
```
|
|
|
|
The descriptor composes `compose.yaml`, `deploy/compose.server.yaml`, the server session-storage
|
|
override, and one read-only Git transport override. **Update workspace repository** fetches a
|
|
candidate on the server; it does not transfer workspace files to the operator workstation.
|
|
|
|
## Complete runtime secrets in Workspace management
|
|
|
|
After repository activation, an authenticated user can:
|
|
|
|
1. Review the configured repository identity and update it without selecting a workspace.
|
|
2. Select a workspace to see the DWH/Evidence credential fields required by its connector modes.
|
|
3. Blind-save or rotate values; returned responses contain status only.
|
|
4. Run **Validate workspace source** and then test its configured connections.
|
|
5. Forget an obsolete value after dependent sessions and jobs have ended.
|
|
|
|
The backend encrypts values in `/data/workspace-secrets`, including the installation-specific
|
|
master key. The server profile persists that directory inside `THT_DATA_ROOT`; no workspace YAML
|
|
path depends on Linux, macOS, or Windows. Plaintext exists only in a restrictive temporary file
|
|
for the duration of a diagnostic, session, or maintenance lease.
|
|
|
|
Authorization is intentionally the current installation-wide authenticated-user policy. A future
|
|
role model or external secret manager can replace that policy without changing workspace source.
|
|
|
|
## Validation and activation behavior
|
|
|
|
Repository update is all-or-nothing: ThothII fetches the configured branch, validates catalog,
|
|
descriptors, Evidence paths, and cross-workspace invariants at one commit, then atomically activates
|
|
the complete candidate. A rejected candidate never replaces the previous active snapshot. The
|
|
application-owned checkout and snapshots are read-only runtime state.
|
|
|
|
Validation proves descriptor and repository structure. **Test connections** additionally
|
|
materializes the current runtime secrets and contacts only the selected workspace's configured
|
|
DWH/Evidence endpoints. Failure does not modify or publish workspace source.
|
|
|
|
## Backup, rotation, and recovery
|
|
|
|
Back up application data and Qdrant consistently. Qdrant backup/restore must cover `qdrant-data`;
|
|
application recovery must cover repository snapshots/state, sessions, settings, Pi state, and the
|
|
entire encrypted `/data/workspace-secrets` directory. Store backup encryption keys separately and
|
|
test restore procedures without production traffic.
|
|
|
|
Rotate DWH/Evidence credentials through Workspace management. Rotate Git access by atomically
|
|
replacing its protected installation file and restarting `core`. Recover a bad source revision by
|
|
reverting or correcting it in the external authoring repository and updating again.
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Meaning and action |
|
|
| --- | --- |
|
|
| Git authentication failed | Verify repository-scoped read permission, branch, key/token, CA, and host-key pinning. |
|
|
| Candidate validation failed | Correct the source repository; the prior active commit remains in service. |
|
|
| Runtime configuration required | Select the workspace and complete all required write-only fields. |
|
|
| Secret store unavailable | Stop writes, preserve `/data/workspace-secrets`, and restore vault plus master key together. |
|
|
| Connection test failed | Rotate the indicated runtime credential or correct the relevant non-secret endpoint. |
|