222 lines
9.0 KiB
Markdown
222 lines
9.0 KiB
Markdown
# Server handoff — preprocessing complete
|
|
|
|
Questo documento è un'istruzione operativa per il Codex eseguito sul server ThothII. Quando
|
|
l'operatore chiede di applicarlo, eseguire i passi nell'ordine indicato e consegnare il report
|
|
finale. La release autorizzata è il tag annotato `260906-preprocessing-complete`.
|
|
|
|
## Obiettivo verificabile
|
|
|
|
Al termine devono essere vere tutte queste condizioni:
|
|
|
|
- il checkout server è esattamente il commit puntato dal tag;
|
|
- il binario host `tht` proviene dallo stesso checkout;
|
|
- la migrazione PostgreSQL del catalogo `013_catalog_preprocessing_state` è terminata con exit 0
|
|
prima dell'avvio del nuovo Core;
|
|
- immagini `core` e `frontend` sono state ricostruite e i servizi sono healthy;
|
|
- il workspace PSD ha completato il preprocessing catalog-driven;
|
|
- Schema, relazioni ed Evidence sono in `<workspace>-reference`, mentre `memory` e
|
|
`solved_question` restano in `<workspace>-memory`;
|
|
- login e nuovo caricamento aprono la superficie Core.
|
|
|
|
## Confini operativi
|
|
|
|
- Conservare descriptor, env, secret, catalogo PostgreSQL, Qdrant, Memory, sessioni e repository
|
|
workspace esistenti.
|
|
- Non stampare descriptor completi, env, secret, connection string o log non sanitizzati.
|
|
- Non usare `reset`, rebase, stash, prune, `down --volumes` o cancellazioni manuali.
|
|
- Non eseguire `workspace preprocess clear`: l'upgrade richiede soltanto il normale `run`, che è
|
|
idempotente, sostituisce i dati derivati e conserva la Memory.
|
|
- Fermarsi davanti a worktree sporco, tag non verificabile, branch divergente, descriptor ambiguo,
|
|
operazioni attive, migrazione fallita o servizi non healthy. Riportare l'evidenza redatta senza
|
|
tentare correzioni distruttive.
|
|
|
|
## 1. Risolvere i target e fare l'inventario
|
|
|
|
Posizionarsi nel checkout server e valorizzare percorsi assoluti reali:
|
|
|
|
```bash
|
|
THTII_REPO=$(git rev-parse --show-toplevel)
|
|
THTII_INSTALLATION=/percorso/assoluto/thothii-installation.yaml
|
|
THTII_RELEASE_TAG=260906-preprocessing-complete
|
|
THTII_WORKSPACE_ID=psd-clinical
|
|
cd "$THTII_REPO"
|
|
```
|
|
|
|
Se il descriptor attivo non è identificabile univocamente dai comandi già usati sul server,
|
|
chiederne il percorso all'operatore. Non cercare secret e non scegliere un file per somiglianza.
|
|
|
|
Eseguire l'inventario in sola lettura:
|
|
|
|
```bash
|
|
git status --short --branch
|
|
git branch --show-current
|
|
git rev-parse HEAD
|
|
git remote -v
|
|
test -f "$THTII_INSTALLATION"
|
|
tht --installation "$THTII_INSTALLATION" status
|
|
```
|
|
|
|
Registrare il vecchio hash. Il branch deve essere `main`, il worktree deve essere pulito e `origin`
|
|
deve puntare al Gitea autorizzato `https://git.tylconsulting.it/mptyl/ThothII.git`. Verificare che
|
|
non siano in corso sessioni Core o preprocessing; in caso contrario fermarsi.
|
|
|
|
**Completamento:** checkout, descriptor, installation Compose e workspace ID sono identificati
|
|
senza ambiguità; il server è inattivo dal punto di vista applicativo e il worktree è pulito.
|
|
|
|
## 2. Integrare l'esatta release
|
|
|
|
```bash
|
|
cd "$THTII_REPO"
|
|
git fetch --prune origin main
|
|
git fetch origin tag "$THTII_RELEASE_TAG"
|
|
test "$(git cat-file -t "$THTII_RELEASE_TAG")" = tag
|
|
THTII_RELEASE_COMMIT=$(git rev-parse "$THTII_RELEASE_TAG^{commit}")
|
|
git switch main
|
|
git merge --ff-only "$THTII_RELEASE_COMMIT"
|
|
test "$(git rev-parse HEAD)" = "$THTII_RELEASE_COMMIT"
|
|
git status --short --branch
|
|
```
|
|
|
|
Il merge deve essere fast-forward e il worktree deve restare pulito. Se `origin/main` contiene
|
|
commit successivi al tag, non integrarli in questa esecuzione: il tag è il confine della release.
|
|
|
|
**Completamento:** `HEAD` coincide byte per byte con il commit del tag annotato.
|
|
|
|
## 3. Installare il CLI della release e validare la configurazione
|
|
|
|
```bash
|
|
cd "$THTII_REPO"
|
|
./scripts/install-tht.sh
|
|
tht version --json
|
|
tht --installation "$THTII_INSTALLATION" update --check-only
|
|
```
|
|
|
|
Leggere strutturalmente dal descriptor i valori `projectDirectory`, `envFile`, `profile` e la lista
|
|
ordinata `overrides`, senza mostrare contenuti protetti. Devono descrivere il checkout corrente e il
|
|
profilo `server`. Il descriptor e l'env esistenti sono configurazione autorevole: non rigenerarli e
|
|
non sostituirli con gli esempi del repository.
|
|
|
|
Se esiste `.tht/<compose-project>/current-image.yaml`, fermarsi e segnalarlo: un pin immagine
|
|
esplicito renderebbe ambiguo il deploy dal checkout.
|
|
|
|
**Completamento:** il nuovo `tht` è installato, il descriptor corrente è valido e nessun pin
|
|
immagine impedisce la ricostruzione.
|
|
|
|
## 4. Preparare il comando Compose dell'installation
|
|
|
|
Costruire un array shell `THTII_COMPOSE` con lo stesso ordine usato da `tht`:
|
|
|
|
1. `docker compose`;
|
|
2. `--project-name thothii-<prime 12 cifre sha256 del percorso canonico del descriptor>`;
|
|
3. `--project-directory <projectDirectory>`;
|
|
4. `--env-file <envFile>`;
|
|
5. `-f <projectDirectory>/compose.yaml`;
|
|
6. `-f <projectDirectory>/deploy/compose.server.yaml`;
|
|
7. ogni override dichiarato, nello stesso ordine;
|
|
8. `-f <directory descriptor>/generated/compose.models.yaml`;
|
|
9. `-f <projectDirectory>/deploy/compose.auth-runtime-projection.yaml` quando il descriptor ha
|
|
`authentication.runtimeProjection`.
|
|
|
|
Per una installation server con Git SSH e senza altri overlay, la forma è:
|
|
|
|
```bash
|
|
THTII_INSTALLATION=$(realpath "$THTII_INSTALLATION")
|
|
THTII_INSTALL_DIR=$(dirname "$THTII_INSTALLATION")
|
|
THTII_ENV=/percorso/assoluto/letto-da-envFile
|
|
THTII_COMPOSE_PROJECT="thothii-$(printf '%s' "$THTII_INSTALLATION" | sha256sum | cut -c1-12)"
|
|
THTII_COMPOSE=(
|
|
docker compose
|
|
--project-name "$THTII_COMPOSE_PROJECT"
|
|
--project-directory "$THTII_REPO"
|
|
--env-file "$THTII_ENV"
|
|
-f "$THTII_REPO/compose.yaml"
|
|
-f "$THTII_REPO/deploy/compose.server.yaml"
|
|
-f "$THTII_REPO/deploy/compose.git-ssh.yaml"
|
|
-f "$THTII_INSTALL_DIR/generated/compose.models.yaml"
|
|
-f "$THTII_REPO/deploy/compose.auth-runtime-projection.yaml"
|
|
)
|
|
"${THTII_COMPOSE[@]}" config --quiet
|
|
```
|
|
|
|
Adattare l'array agli override realmente dichiarati. Non usare il blocco di esempio se il
|
|
descriptor differisce.
|
|
|
|
**Completamento:** `config --quiet` termina con exit 0 usando esattamente l'identità e i file della
|
|
installation già attiva.
|
|
|
|
## 5. Costruire, migrare e riavviare
|
|
|
|
La build può avvenire mentre i vecchi container sono ancora in esecuzione: i container mantengono
|
|
il loro image ID. Fermare Core e frontend soltanto dopo una build riuscita.
|
|
|
|
```bash
|
|
"${THTII_COMPOSE[@]}" build core frontend
|
|
"${THTII_COMPOSE[@]}" stop frontend core
|
|
"${THTII_COMPOSE[@]}" up --detach catalog-db qdrant embedding
|
|
"${THTII_COMPOSE[@]}" run --rm catalog-migrate
|
|
"${THTII_COMPOSE[@]}" run --rm embedding-model-init
|
|
tht --installation "$THTII_INSTALLATION" start
|
|
tht --installation "$THTII_INSTALLATION" status
|
|
tht --installation "$THTII_INSTALLATION" doctor --json
|
|
```
|
|
|
|
`catalog-migrate` deve terminare con exit 0. `embedding-model-init` è one-shot: `exited (0)` è il
|
|
suo stato corretto. Se un passo fallisce dopo lo stop, lasciare i container e i volumi disponibili
|
|
per diagnosi e raccogliere soltanto:
|
|
|
|
```bash
|
|
tht --installation "$THTII_INSTALLATION" status
|
|
tht --installation "$THTII_INSTALLATION" logs
|
|
```
|
|
|
|
**Completamento:** migrazione completata, servizi persistenti healthy e job embedding terminato con
|
|
exit 0.
|
|
|
|
## 6. Eseguire una volta il preprocessing completo
|
|
|
|
Ispezionare prima le precondizioni:
|
|
|
|
```bash
|
|
tht --installation "$THTII_INSTALLATION" \
|
|
workspace inspect --workspace "$THTII_WORKSPACE_ID" --json
|
|
```
|
|
|
|
Lo stato atteso dopo l'upgrade è `required`. Se è `blocked`, correggere soltanto il prerequisito
|
|
indicato. Se è `running`, fermarsi perché esiste un'operazione concorrente. Se è `failed`, leggere
|
|
il solo ultimo diagnostico e i log sanitizzati del Core prima di ritentare.
|
|
|
|
Quando le precondizioni sono soddisfatte, eseguire:
|
|
|
|
```bash
|
|
tht --installation "$THTII_INSTALLATION" \
|
|
workspace preprocess run --workspace "$THTII_WORKSPACE_ID" --json
|
|
|
|
tht --installation "$THTII_INSTALLATION" \
|
|
workspace inspect --workspace "$THTII_WORKSPACE_ID" --json
|
|
```
|
|
|
|
Il secondo inspect deve riportare il workspace pronto e la revisione metadati processata uguale a
|
|
quella corrente. Il run legge tabelle, colonne, descrizioni, sensibilità e foreign key dal Catalogo
|
|
PostgreSQL; il workspace YAML fornisce soltanto identità ed eventuale Evidence. Un workspace senza
|
|
Evidence è valido. Il run effettua anche il cutover dall'eventuale collezione Qdrant legacy,
|
|
preservando `memory` e `solved_question`.
|
|
|
|
**Completamento:** preprocessing riuscito una volta, Core ammesso e Memory preservata.
|
|
|
|
## 7. Accettazione e report
|
|
|
|
Verificare, senza creare una sessione reale se non richiesto dall'operatore:
|
|
|
|
- `git rev-parse HEAD` uguale a `git rev-parse 260906-preprocessing-complete^{commit}`;
|
|
- worktree pulito;
|
|
- `tht doctor --json` con esito positivo;
|
|
- `catalog-db`, Qdrant, embedding, Core e frontend healthy;
|
|
- ultimo `workspace inspect` pronto;
|
|
- login o hard refresh posizionati sulla pagina Core;
|
|
- **Administration → Preprocessing** mostra `Status: Ready` e **Run again**;
|
|
- **New session** è abilitato.
|
|
|
|
Consegnare un report breve con vecchio hash, nuovo hash, tag, versione `tht`, exit della migrazione,
|
|
stato servizi e risultato preprocessing. Redigere URL interni, nomi utente e qualsiasi dato
|
|
operativo sensibile.
|