ThothII/docs/operations/server-codex-handoff.md

# Consegna a Codex sul server: ThothII e Omics Portal

Revisione: **26 settembre 2026**. Destinazione: Datamart Builder nel portale
Omics esistente, non un nuovo sito standalone. Questo documento è la procedura
di riferimento per questa consegna e sostituisce le precedenti istruzioni di
trasporto/pubblicazione del codice Omics. La distribuzione parte dai sorgenti
ThothII aggiornati su `main` e dal branch Omics disponibile su GitHub; nessuna
replica del repository Omics ad altri servizi fa parte dell'intervento.

## Risultato da ottenere e limiti

- L'utente entra in Omics come oggi, sceglie **Datamart Builder** e trova ThothII
  già autenticato, senza un secondo login.
- Omics mantiene header, navigazione sinistra, lingua, tema, fullscreen, nome
  utente e logout. ThothII occupa soltanto la zona centrale: **embedded/upstream**.
- I dati e le identità esistenti, i workspace, i modelli approvati e le credenziali
  del server restano quelli del server. Il Mac rimane **full/local**, default EN.
- L'intervento comprende il codice e la configurazione di entrambi gli
  applicativi, la rigenerazione delle proiezioni, le immagini e il collaudo.
  Un pull da solo non conclude l'installazione.

Codex può fare l'inventario, preparare modifiche e test isolati. Prima del fermo,
delle migrazioni, della modifica del proxy o della ricreazione di servizi
operativi, presenta i comandi risolti, backup e rollback e ottieni conferma della
finestra di rilascio. Ferma il passaggio interessato se manca una credenziale,
una decisione sulla migrazione o un prerequisito; non aggirare i controlli.
Non modificare Authentik o il DWH per correggere la UI. Il DWH resta read-only.
Non cancellare volumi, dati o modifiche locali e non stampare segreti nei report.

## 1. Identificare l'installazione realmente in uso

Leggi `AGENTS.md` e `PROJECT_STATE.md` nel checkout ThothII aggiornato. Individua
il checkout operativo Omics, normalmente `/home/chirone/omics_portal`; conferma
il percorso prima di usarlo. Registra per **entrambi** i progetti:

1. Percorso, branch, SHA, stato della working tree e revisioni delle immagini
   effettivamente in esecuzione. Il checkout appena aggiornato può non coincidere
   con quello da cui sono stati creati i container.
2. Nomi progetto Compose, file Compose/override ordinati, env file, servizi,
   mount, porte e reti. Leggi le label Compose dei container per ricostruire
   l'avvio; filtra gli inspect, evitando dump di variabili segrete.
3. Percorso assoluto del `thothii-installation.yaml`, suo schema/profile,
   `projectDirectory`, `envFile`, `overrides`, `authentication`, `shell` e modello
   dei dati persistenti. Usa solo percorsi Linux reali e file che esistono.
4. Configurazione effettiva del core: modalità auth, `THOTH_PUBLIC_EXPOSURE`,
   `THT_SESSION_STORAGE`, binding workspace/database, percorsi degli archivi
   Evidence e Memory e delle credenziali Pi/provider.
5. Origine HTTPS pubblica del portale, punto di terminazione TLS, percorso
   autenticato delle API, alias di rete e possibilità di accesso diretto al core.

**Completato quando:** esiste un inventario senza segreti e ogni comando di
avvio è ricostruibile con percorsi/progetti effettivi. Non usare gli script
temporanei `/private/tmp/…` o i percorsi `/Users/mp/…` del Mac. Gli override vanno
conservati in un percorso operativo stabile sul server.

## 2. Verificare le revisioni dei due applicativi

### ThothII

Il checkout aggiornato deve essere sulla `main` di Gitea (`origin`) e includere almeno
`0d2e573e` (correzione della vista sessione del 26 settembre) e questo documento.
Il branch `codex/guided-standalone-install` contiene un processo di nuova installazione
ancora in lavorazione: non usarlo per questo aggiornamento e non eseguire
`tht setup --complete` sull'installazione server esistente. Registra lo SHA effettivo e
confrontalo con `origin/main` senza modificare il checkout operativo:

```bash
git fetch origin main
git status --short --branch
git rev-parse HEAD
git rev-parse origin/main
git rev-list --left-right --count HEAD...origin/main
git merge-base --is-ancestor 0d2e573e HEAD
```

La divergenza ideale è `0 0` e la working tree è pulita. Se il controllo dell'antenato
fallisce, o se il server ha commit o modifiche locali, prepara e verifica la revisione
approvata prima di toccare l'installazione; non usare reset o force push. Non ricostruire
a mano le singole modifiche UI: la revisione di `main` contiene shell, autenticazione,
i18n, workflow bilingue, amministrazione, typography e navigazione aggiornate.

### Omics Portal

Il pull di ThothII **non aggiorna Omics**. Consegna Omics verificata su GitHub:

- Repository: `https://github.com/Dallavilla-Tiziano/omics_portal.git`.
- Branch: `codex/thothii-embedded-shell`.
- SHA della consegna: `fca10901a73666ca257d8f4cc4b77066295c400a`.
- Commit funzionale della shell: `95154e179144e2453b37ef2a63a65d6f377e4cf8`.

Nel checkout Omics confermato, acquisisci senza fare un pull/merge implicito:

```bash
cd /home/chirone/omics_portal
git status --short --branch
git rev-parse HEAD
git fetch --no-tags https://github.com/Dallavilla-Tiziano/omics_portal.git \
  refs/heads/codex/thothii-embedded-shell:refs/remotes/thothii-delivery/omics-shell
git rev-parse refs/remotes/thothii-delivery/omics-shell
git merge-base --is-ancestor 95154e179144e2453b37ef2a63a65d6f377e4cf8 \
  refs/remotes/thothii-delivery/omics-shell
git diff --stat HEAD...refs/remotes/thothii-delivery/omics-shell
```

Confronta lo SHA acquisito con quello sopra. In caso di consegna diversa chiedi
quale revisione usare. Confronta inoltre le modifiche con i progressi del server:
non sostituire l'intero portale con un checkout più vecchio. Se la consegna è già
integrata verifica i file, senza ripetere il merge; altrimenti prepara la sua
integrazione in un branch/worktree di revisione dal codice operativo. Risolvi
eventuali conflitti preservando i cambiamenti del server, testa, quindi applica
la revisione concordata nel rilascio. Non fare reset o force push.

I dettagli tecnici locali in `docs/thothii-integration.md` di Omics sono utili,
ma il percorso operativo di questa consegna è quello di **questo documento**.
La pubblicazione del codice Omics su altri remote non è un prerequisito.

**Completato quando:** una revisione integrata Omics conserva le funzionalità del
server e soddisfa tutti i controlli dei file nella sezione 4.

## 3. Adeguare ThothII senza importare la configurazione del Mac

### CLI, descrittore e proiezioni

Aggiorna il **CLI nativo host** dal checkout ThothII approvato, conservando il
vecchio binario per rollback. Non confonderlo con il CLI Python interno al core:

```bash
./scripts/install-tht.sh
command -v tht
tht --help
```

Il comando installa normalmente in `/usr/local/bin` e verifica la risoluzione
su PATH. Se il server usa un'altra directory, mantieni quella usando
`THT_INSTALL_DIRECTORY` con un percorso assoluto. Conserva proprietario e
permessi protetti del descrittore (`0600` o `0400`). Nel descrittore esistente
schema v2 modifica la sezione seguente, preservando gli altri valori:

```yaml
shell:
  mode: embedded
  defaultLocale: en
  adapter: omics-portal
```

`en` è il fallback UI, non forza l'inglese sul portale: in embedded prevale la
lingua renderizzata da Django. Mantieni il `profile` server approvato e i percorsi,
la project/installation identity, lo storage e gli override del server. Se il
descrittore manca o è legacy, prepara una migrazione separata dopo l'inventario;
non rilanciare il setup locale e non copiare il descrittore Mac.

Usa una variabile di lavoro dedicata, valorizzata con il percorso **confermato**:

```bash
THTII_INSTALLATION=/percorso/reale/thothii-installation.yaml
tht --installation "$THTII_INSTALLATION" installation generate
```

La generazione non avvia i servizi. Controlla `generated/frontend/config.js` e
il suo mount read-only nel Compose generato; prima dell'override Omics deve
contenere `backendBaseUrl: "/api"` e la shell embedded completa. Conserva anche
le proiezioni generate di modelli/settings/Pi. Non mantenere copie manuali dei
file generati: `thothii-installation.yaml` resta la sorgente authored.

### Autenticazione già fornita dal portale

Nell'override Compose persistente dell'installazione deve esserci:

```yaml
services:
  core:
    environment:
      AUTH_MODE: upstream
```

Aggiungi il percorso dell'override all'elenco `overrides` del descrittore se non
è già caricato. Controlla il Compose risolto: scrivere `AUTH_MODE` nel solo file
env non garantisce che la variabile arrivi al container.

- `authentication.configDirectory` e `THT_AUTH_CONFIG_ROOT` devono indicare la
  directory protetta prevista, **senza un `auth.yaml` local/OIDC letto dal core**.
  Non cancellare un file esistente: se trovato, fermati e prepara il cambio auth
  con backup e una directory dedicata. `AUTH_MODE` insieme al file è rifiutato.
- Per Omics non usare `authentication.runtimeProjection` né
  `THT_AUTH_RUNTIME_PROJECTION_ROOT`: appartengono all'accesso local/OIDC diretto.
- Non creare utenti/password ThothII, nuovi client OIDC o callback per questo
  embedding. Non esiste `tht auth configure --mode upstream`.
- Preserva la coppia stabile `(issuer, subject)` degli utenti (`portal`, ID
  Django); cambiarla può rendere invisibili le sessioni dei proprietari esistenti.

### Dati, storage e prerequisiti non grafici

La release corrente usa catalogo metadati interno PostgreSQL, workspace schema
v4, Installation Model Catalog v2, Qdrant e Ollama per embedding; Pi gira nel
core. Mantieni i provider e i binding reali del server, incluse credenziali e CA.
I default del Mac non sono una richiesta di cambiare modello o database.

Il catalogo metadati e l'eventuale database delle sessioni sono **due funzioni
distinte**. Con `THOTH_PUBLIC_EXPOSURE=true`, il core rifiuta
`THT_SESSION_STORAGE=local`: verifica che il percorso PostgreSQL delle sessioni
sia già configurato e validato. Se manca, presenta il piano di provisioning e
migrazione; non disabilitare il controllo public-exposure per ottenere l'avvio.
L'overlay session-server è opt-in e non migra automaticamente i vecchi archivi.

Se la versione operativa precede questi contratti, risolvi prima la migrazione
dei dati con backup verificati. Le migrazioni del catalogo si eseguono tramite
il job esplicito `catalog-migrate`; quelle delle sessioni, quando necessarie e
approvate, tramite `session-migrate`. Nessuna riguarda il DWH o è sostituita da
una sincronizzazione di schema dall'interfaccia.

**Completato quando:** il descrittore genera correttamente; la configurazione
risolta contiene shell embedded, upstream senza doppia auth, storage compatibile,
mount e reti corretti; ogni differenza infrastrutturale ha un piano approvato.

## 4. Verificare e integrare i file Omics

| File nel repository Omics | Risultato obbligatorio |
| --- | --- |
| `templates/kokoro/datamart_builder.html` | Mount `#root` nello stesso documento Django, senza iframe; altezza contenuta sotto la topbar e layout centrale responsive. Carica config, override limitato e asset in quest'ordine. |
| `templates/base.html` | `{% get_current_language as CURRENT_LANGUAGE %}` e `<html lang="{{ CURRENT_LANGUAGE }}">`, preservando i block del template. |
| `templates/partials/topbar.html` | `select.omics-language-select[data-lang]` con lingua Django, form `set_language` POST/CSRF/next; pulsante fullscreen con label ingresso/uscita e stato accessibile. Mantieni nome/logout Omics. |
| `static/js/app.js` | Fullscreen reale del documento con `requestFullscreen`/`exitFullscreen`; ascolta gli eventi del browser, inclusa uscita con Esc, aggiorna icona/stato/label e gestisce rifiuti senza simulare successo. |
| `locale/it/LC_MESSAGES/django.po` | Traduzioni dei nuovi controlli fullscreen; compilazione del catalogo distribuito. |
| `kokoro/datamart_catalog_views.py` e routing | La pagina richiede `datamart_builder.access`; l'endpoint `/datamart-builder/api-auth` verifica la sessione Django e restituisce identità verificata o 403. Conserva questa parte già esistente. |
| `nginx/nginx.conf` | API protette verso il core, asset/config verso il frontend, origine e SSE coerenti. Conserva anche le altre route del portale. |
| `kokoro/templatetags/vite.py` | Manifest da `http://thothii-frontend:8080/.vite/manifest.json`, asset dal manifest, cache di 30 secondi. |
| `kokoro/test_thothii_shell.py`, `test_support/thothii/` | Test isolati della pagina e dei controlli, da eseguire prima del rilascio. |

Il template deve fare questo **prima** di `{% vite_assets %}`:

```html
<script src="/datamart-builder/config.js"></script>
<script>
  window.__THOTHII_CONFIG__ = Object.assign({}, window.__THOTHII_CONFIG__ || {}, {
    backendBaseUrl: '/datamart-builder/api'
  });
</script>
```

L'override non deve sostituire l'intero oggetto perdendo `shell`. Nel browser il
risultato deve avere `/datamart-builder/api` e `shell.mode === "embedded"`.
`config.js` deve avere `Cache-Control: no-store`; gli asset con hash possono
avere cache lunga. Non codificare a mano i nomi dei bundle Vite.

Il tema deve essere espresso come `data-bs-theme="light"` o `"dark"` su `html`.
`OmicsPortalAdapter` in ThothII osserva quel dato, legge il `data-lang` renderizzato
dal selettore e lo stato fullscreen. Non richiede nuovi eventi, handshake o
token JavaScript. Se il contesto manca va corretto il template, non aggirato
l'errore con un header full. I dettagli del portale restano nel solo adapter.

### Proxy e identità: controllo obbligatorio

Il flusso è browser → Nginx Omics → controllo Django → core ThothII:

1. `/datamart-builder/api/…` usa `auth_request /_thothii_auth`.
2. La location interna interroga `/datamart-builder/api-auth` usando il cookie
   Omics. Django risponde 200 se autorizzato, 403 senza sessione/capability.
3. Nginx usa solo gli header **della risposta Django** e sovrascrive gli eventuali
   valori client: `X-Thoth-Principal-Issuer: portal`,
   `X-Thoth-Principal-Subject: <user.pk>`, `X-Thoth-Principal-Display-Name` e
   `X-Thoth-Is-Admin: true|false` secondo `is_authentik_admin(user)`.
4. Il proxy rimuove `Cookie`, `Authorization` e `X-Authenticated-User` prima del
   core, toglie il prefisso API e inoltra a `thothii-core:8787`. Non usare qui
   gli header `X-Thoth-Trusted-*` dell'esempio generico a due hop.
5. Config/asset e manifest arrivano da `thothii-frontend:8080`. Omics web deve
   raggiungere il manifest; Nginx deve raggiungere entrambi gli alias privati.

Integra i servizi nella rete effettiva del portale, con alias non ambigui;
non collegare due core candidati con lo stesso alias. Il core upstream deve
essere irraggiungibile direttamente da browser/client non fidati, inclusi
percorsi alternativi attraverso un frontend o proxy non protetto.

Conserva buffering/cache disattivati e timeout lunghi per SSE anche nel proxy
a monte. Verifica l'Origin delle scritture: il codice Omics contiene la mappa
esatta da `https://aritmolab.policlinicosandonato.it` a
`http://aritmolab.policlinicosandonato.it` per la terminazione TLS esterna.
Conferma che la topologia sia ancora quella. Se differisce, correggi Host,
protocollo e mappa esatta con un test di rifiuto cross-origin; non cancellare
Origin, non usare wildcard né rendere fidati gli header forniti dal browser.

Riferimento per errori 401/403 e contratto completo:
[autenticazione upstream](../install/authentication-upstream.md).

## 5. Test, backup e rilascio coordinato

Dal checkout Omics integrato, senza database operativo o volumi collegati:

```bash
docker build -f test_support/thothii/Dockerfile -t omics-portal:thothii-shell-tests .
docker run --rm --network none omics-portal:thothii-shell-tests
```

In ThothII verifica la build di frontend/core, i test auth e shell e la
generazione del descrittore con il CLI aggiornato. I test locali alla consegna
includono 768 test frontend, 20 scenari browser e build documentale strict;
non certificano il portale/IdP né i dati del server.

Prima del rilascio prepara un piano con i **comandi esatti risolti**. Per
installazioni già governate dal CLI usa `tht --installation …`; per launcher
server personalizzati conserva progetto, ordine di tutti gli override e bind.
Non alternare i due lifecycle se cambiano la project identity o i volumi.

Ordine da applicare nella finestra confermata:

1. Metti al sicuro revisioni, binario host, descrittore/env/override, immagini e
   backup consistenti di catalogo, sessioni, registry/Evidence/Memory, settings,
   Pi e indici. Proteggi i backup che contengono segreti. Verifica il ripristino
   prima di una migrazione non reversibile e gestisci le sessioni in corso.
2. Genera le proiezioni dell'installazione; costruisci **core e frontend** dai
   sorgenti approvati. Avvia i servizi di supporto necessari e, se richiesto dal
   salto di versione, esegui le migrazioni esplicite con exit 0 prima del core.
   Il normale `tht start --build` coordina il lifecycle, non è frontend-only.
3. Ricrea i servizi applicativi ThothII con configurazione embedded/upstream e
   conserva il progetto/dati approvati. Controlla health e diagnostica:

   ```bash
   tht --installation "$THTII_INSTALLATION" status
   tht --installation "$THTII_INSTALLATION" doctor --json
   ```

4. Distribuisci la revisione Omics integrata tramite il suo normale rilascio,
   includendo `web`, statici/cataloghi e configurazione `nginx`. Il suo entrypoint
   esegue `migrate`, `compilemessages` e `collectstatic`: le modifiche della shell
   non aggiungono migrazioni Django, ma controlla quelle pendenti del server prima
   del riavvio. Verifica anche il catalogo Superset richiesto dalla build Omics.
5. Esegui `nginx -t` nel servizio candidato e applica il reload/riavvio secondo
   la topologia registrata. Dopo la ricreazione dei container verifica che il
   proxy risolva gli alias ai nuovi indirizzi, non a IP Docker precedenti.
6. Attendi almeno 30 secondi per la cache manifest Django o invalidala con il
   meccanismo del portale. Verifica asset/config e svolgi il collaudo seguente.

Se uno step fallisce non marcare l'installazione conclusa. Un core healthy non
prova che auth, UI embedded o scritture attraverso il proxy funzionino.

## 6. Accettazione prima di dichiarare completato

Usa account di prova autorizzati e dati non operativi per i test che scrivono.
Le verifiche che richiedono login interattivo possono essere svolte dall'operatore:
riporta esplicitamente quelle ancora da fare, senza spuntarle per deduzione.

- **Accesso:** login Omics, apertura da menu, nessun login/header ThothII. `/me`
  su `/datamart-builder/api/me` restituisce identità e permessi corretti;
  `session`/`csrfToken` sono null in upstream.
- **Dinieghi:** senza sessione o capability il proxy nega; header principal
  falsificati non danno accesso. Utente normale senza controlli admin; admin
  autorizzato con controlli coerenti. Nessuna route diretta aggira il proxy.
- **Lingua e continuità:** IT/EN prima e dopo l'apertura, cambio attraverso Omics,
  ripristino della selezione dopo reload senza generazione automatica. Nuove
  sessioni ricevono la lingua UI; sessioni riprese mantengono
  `interaction_language`. Per quelle legacy la prima ripresa fissa la lingua
  del workspace in modo idempotente. SQL e contenuti authored non sono tradotti.
- **Tema/fullscreen:** light/dark cambia anche ThothII, incluse finestre e menu;
  fullscreen nasconde il bordo browser, sostituisce l'icona e torna normale con
  Esc. Header/sidebar Omics mantengono il proprio aspetto.
- **Logout:** il logout è soltanto quello Omics. Ritorno alla pagina e
  riconnessione ricontrollano l'accesso; non promettere revoca istantanea di uno
  stream già aperto in un'altra scheda.
- **Workflow:** una sessione di prova autorizzata può essere creata, ricevere
  eventi SSE e domande/scelte nella lingua corretta, salvare e riprendere senza
  perdere proprietà. Le scritture same-origin funzionano, quelle cross-origin
  non autorizzate vengono negate.
- **Amministrazione/UI:** Database, Memory ed Evidence leggibili, font/layout
  aggiornati e nessuna propagazione del reset CSS alla topbar Omics. Le memory
  FAKE sono solo esempi UI isolati, non da importare nel catalogo o nel recall.
  Puntino readiness Workspace, unico bottone Sessione, tab con bordi uniformi;
  accordion inizialmente chiuso, un solo pannello aperto, selezione per lista,
  scroll interno e nessuna frase “Inizia con Sessione”.
- **Operatività:** nessun errore di config/auth nei log, mount e permessi corretti,
  indici/cataloghi e dati precedenti disponibili, nessuna modifica al DWH/IdP.

Compila il report con SHA ThothII/Omics, immagini, percorsi configurazione,
comandi eseguiti, risultati e prove manuali pendenti, senza cookie o token.
La [matrice auth completa](../testing/authentication-manual-acceptance.md)
approfondisce i casi di sicurezza.

## 7. Rollback

Ripristina la coppia compatibile di codice/immagini **Omics e ThothII**, il CLI,
descrittore e proiezioni registrati, seguendo il lifecycle approvato. Riavvia il
proxy se necessario per DNS/config e ricontrolla manifest, accesso e SSE.
I dati restano preservati: nessun `down --volumes`, cancellazione di archivi o
reset distruttivo. Se il rilascio ha migrato uno schema o scritto dati non
compatibili con la versione precedente, usa il piano di ripristino dati approvato,
non un semplice downgrade d'immagine. Il rollback termina solo dopo il collaudo
della versione ripristinata.