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:

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:

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:

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

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:

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:

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 %}:

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

5. Test, backup e rilascio coordinato

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

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:

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