ThothII/docs/install/server-workspace-registry.md

Server workspace repository installation

This manual supplements 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:

/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.

Schema v3 is the only accepted workspace descriptor. Schema v1 and v2 workspace descriptors are rejected before activation.

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:

THT_BIN=/srv/thothii/operator/tht
INSTALLATION=/srv/thothii/operator/thothii-installation.yaml
"$THT_BIN" --installation "$INSTALLATION" start
"$THT_BIN" --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

Chiavi DWH REST per installazione

Un'installazione server che seleziona rest_api usa una chiave DWH nel vault cifrato o nel file API_KEY_FILE; postgres_direct e ssh_tunnel non usano chiavi dwh-auth. Il servizio dwh-auth del DWH ha lifecycle systemd separato e non appartiene al Compose di ThothII. Vedere enrollment client e guida server DWH.

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.