mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: record P7 publication + live stack (pending VPN)

Browse Source
This commit is contained in:
marcopan
2026-08-13 16:41:46 +02:00
parent 3046ac34c6
commit 84b233d937
3 changed files with 75 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/install/psd-workspace-setup.md
+39 -88
View File
@@ -1,107 +1,58 @@
# Policlinico San Donato — setup workspace (nuova gestione)
Guida operativa per collegare ThothII al DWH di PSD con il nuovo sistema (registry Git + descriptor
v3 + `thothctl`). Lo stato attuale:
v3 + `thothctl`).
- il repository PSD **è già stato ristrutturato** e committato localmente in
`/Users/mp/projects/tht-workspace-psd` (layout P1.1: `thoth-workspaces.yaml` +
`psd-clinical/workspace.yaml` + `psd-clinical/evidence/` + `psd-clinical/schema/annotations.yaml`);
- la **validazione locale** del registry è già passata (descriptor v3 valido, 36 Evidence
materializzate, 42 KB di annotations sincronizzate, docs generate).
## Stato attuale (2026-08-13)
Rimangono i passi che richiedono segreti/accesso. I template pronti sono in `deploy/psd/`
(`*.example`).
- **Repository PSD pubblicato:** `https://github.com/mptyl/tht-workspace-psd` (privato), branch
`main`, commit `d4f9185`. Layout P1.1 già migrato e validato.
- **Deploy key SSH** (read-write, senza passphrase) generata in
`deploy/psd/secrets/git-ssh-key` e registrata sul repo come deploy key `thothii-psd`; il remote
Git usato dall'installazione è `git@github.com:mptyl/tht-workspace-psd.git`.
- **Config operatore pronta** (file reali gitignored in `deploy/psd/`): `operator.env`,
`workspace-bindings.env`, `thothii-installation.yaml`, `connector-secrets.yaml` e i secret
`secrets/` (API key DWH riusata, pi-auth, secret bundle, chiave SSH, known_hosts). Nessuna CA:
il DWH REST usa HTTPS pubblico (`THT_SSL_CA` era vuoto).
- **Stack avviato** (progetto `thothii-70417a3e30ea`, via `thothctl start`): `qdrant`, `embedding`
(con `qwen3-embedding:0.6b`), `core`, `frontend` sani. Il registry ha **clonato e attivato**
`psd-clinical` (stato `ready`).
- **`thothctl workspace inspect --workspace psd-clinical` = OK** (identità descrittore/catalogo/
config risolte con i bindings DWH).
- **Bloccante residuo: VPN.** `supabase-aritmolab.policlinicosandonato.it` non risolve
(`NXDOMAIN`) → il preprocessing DWH e le sessioni live non possono ancora partire.
## 1. Pubblica il repository PSD su GitHub
## Avvio/arresto (canonico)
Crea un repository Git **privato** su GitHub e pubblicalo:
Usare `thothctl` (stesso project name, quindi stessi volumi named):
```bash
git -C /Users/mp/projects/tht-workspace-psd remote add origin <URL-repo>
git -C /Users/mp/projects/tht-workspace-psd push -u origin main
THOTHCTL=dist/thothctl/thothctl-darwin-arm64
"$THOTHCTL" --installation "$(pwd)/deploy/psd/thothii-installation.yaml" start
"$THOTHCTL" --installation "$(pwd)/deploy/psd/thothii-installation.yaml" workspace inspect --workspace psd-clinical --json
"$THOTHCTL" --installation "$(pwd)/deploy/psd/thothii-installation.yaml" stop
```
Oppure fornisci URL + credenziali e lo pusho io.
> **Nota project name:** `thothctl` calcola un project name stabile dall'installation descriptor
> (`thothii-<hash>`); `docker compose` "a mano" usa invece `name: thothii` dal `compose.yaml`, quindi
> i volumi named non coinciderebbero. Perciò per lo stack si usa `thothctl start` (non
> `compose-with-preflight.sh up`).
## 2. Prepara i segreti (in `deploy/psd/secrets/`, non tracciati)
| File | Contenuto | Riuso |
| --- | --- | --- |
| `psd-clinical-dwh-api-key` | la `X-API-Key` del DWH REST | `THT_DWH_API_KEY` esistente |
| `psd-clinical-dwh-ca.pem` | CA interna (solo se il REST la presenta) | `THT_SSL_CA` esistente |
| `pi-auth.json` | profilo Pi con le credenziali LLM (zai/deepseek/qwen) | esistente |
| `thothii.secrets` | bundle secret dell'app | esistente |
| `git-credentials` | credenziali HTTPS del remote Git privato | nuova |
> **Nota CA**: il *preprocessing* DWH via REST supporta la CA (`TLS_CA_FILE`). Il *diagnostic* di
> readiness REST, invece, rifiuta una CA per-request privata: se il ping fallisce per la CA, va
> reso trusted a runtime oppure si adatta `diagnostics.dwh_rest` nel descriptor Git.
## 3. Compila i file operatore (dai template)
## Completare quando la VPN è attiva
```bash
cd deploy/psd
cp workspace-bindings.env.example workspace-bindings.env
cp operator.env.example operator.env
cp thothii-installation.yaml.example thothii-installation.yaml
"$THOTHCTL" --installation "$(pwd)/deploy/psd/thothii-installation.yaml" workspace preprocess run --workspace psd-clinical --json
```
Compila i placeholder con i valori reali (remote GitHub, path assoluti). Il bindings file per PSD è:
Se si ferma per le join (`manual_review_required`): rivedere `psd-clinical/schema/annotations.yaml`
nel repo, commit+push, poi `workspace schema accept --run <run-id> --yes` e
`workspace preprocess run --resume <run-id>`.
```dotenv
THT_WS_PSD_CLINICAL_DWH_TRANSPORT=rest_api
THT_WS_PSD_CLINICAL_DWH_BASE_URL=https://supabase-aritmolab.policlinicosandonato.it/dwh/
THT_WS_PSD_CLINICAL_DWH_API_KEY_FILE=/run/secrets/psd-clinical-dwh-api-key
```
Poi aprire `http://localhost:8080`, selezionare `psd-clinical` e creare una sessione con una domanda.
## 4. Genera il connector override
## Cosa è già stato fatto
```bash
scripts/generate-connector-secrets-override.sh --bindings-env deploy/psd/workspace-bindings.env --operator-env deploy/psd/operator.env --output deploy/psd/connector-secrets.yaml --service workspace-maintenance --role all
```
## 5. Avvia lo stack (VPN attiva; internet per scaricare il modello)
```bash
scripts/compose-with-preflight.sh --env-file deploy/psd/operator.env -f compose.yaml -f deploy/compose.local.yaml -f deploy/compose.git-https.yaml -f deploy/psd/connector-secrets.yaml up --build -d
```
Il primo avvio esegue `embedding-model-init`, che scarica `qwen3-embedding:0.6b` nel volume
`embedding-models` e poi sblocca `core`.
## 6. Attiva e valida il workspace
```bash
curl --fail --silent http://127.0.0.1:8787/health
thothctl --installation deploy/psd/thothii-installation.yaml workspace inspect --workspace psd-clinical --json
```
## 7. Preprocessing (DWH → FK → schema → Evidence)
```bash
thothctl --installation deploy/psd/thothii-installation.yaml workspace preprocess run --workspace psd-clinical --json
```
Se il run si ferma per la revisione delle join (`manual_review_required`):
```bash
# il curatore rivede i candidati e pubblica psd-clinical/schema/annotations.yaml (commit+push),
# poi l'installazione fa pull, e si esegue:
thothctl --installation deploy/psd/thothii-installation.yaml workspace schema accept --workspace psd-clinical --run <run-id> --yes --json
thothctl --installation deploy/psd/thothii-installation.yaml workspace preprocess run --workspace psd-clinical --resume <run-id> --json
```
## 8. Testa una domanda reale
Apri l'app (`http://localhost:5173`), seleziona `psd-clinical` e crea una sessione con una domanda
in linguaggio naturale. Segui le 8 fasi e conferma ai gate fino all'SQL finale.
## Cosa serve ancora da te
1. **URL + credenziali del repo GitHub** del workspace PSD (passo 1).
2. **X-API-Key DWH** (+ CA, se serve) riusabili dall'ambiente attuale (passo 2).
3. Conferma del **provider/modello LLM** di default (`zai/glm-5.2` è già impostato nel descriptor).
4. Conferma dell'**endpoint ping** REST del DWH (`POST /rpc/ping` con `X-API-Key`) per il
`diagnostics.dwh_rest` del descriptor.
Con questi quattro elementi completiamo i passi 2–4 insieme e lanciamo lo smoke live.
- Ristrutturazione del repo PSD nel layout P1.1 + validazione locale.
- Pubblicazione GitHub + deploy key + config operatore completa (bindings/secret/override).
- Avvio stack + attivazione registry + `thothctl inspect` verde.
- Restano solo: **VPN attiva** → `preprocess run` → smoke live di una domanda PSD (P8 L2).