# 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 ``, 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 ``` 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: `, `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.