ThothII/docs/operations/shell-and-localization.md

Shell, autenticazione e lingue

Questa è la procedura operativa del rendering corrente. Leggerla insieme a architettura full/embedded, autenticazione upstream e contratto PortalAdapter. La specifica approvata documenta la progettazione, non sostituisce i vincoli verificati nel codice e riportati qui.

Scegliere il contenitore

La modalità della shell è indipendente dal profilo di distribuzione e dal metodo di autenticazione. Un server può ospitare full; un ambiente locale può ospitare embedded per provare un'integrazione.

Destinazione	Shell	Autorità di accesso	Login/logout visibile
Mac attuale	full, default en	auth.yaml local	ThothII
Server autonomo	full	auth.yaml OIDC	ThothII, con redirect al provider
Datamart Builder in Omics	embedded, adapter Omics	core AUTH_MODE=upstream, sessione Omics al proxy	Solo Omics

Non confondere la lingua inglese iniziale del Mac con quella del workspace o delle sessioni già create. Non copiare sul server l'intero descrittore del Mac: contiene percorsi e scelte locali, oltre a full.

Per questo Mac, nel descrittore installato:

shell:
  mode: full
  defaultLocale: en

Per il server Omics:

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

L'assenza di shell conserva embedded con adapter Omics. Un nome adapter sconosciuto è un errore, non una richiesta di fallback a full. Full ignora l'adapter Omics riconosciuto e non lo istanzia. Un locale ben formato per cui non esiste ancora un catalogo usa l'inglese nell'interfaccia.

defaultLocale è il valore iniziale, non un vincolo che annulla ogni scelta dell'utente. Full ricorda lingua e tema nel browser; embedded segue soltanto Omics. Le preferenze non modificano il descrittore installato.

Applicare una modifica all'installazione

Per una nuova installazione autonoma, selezionare esplicitamente full:

tht setup --profile local --shell-mode full --shell-default-locale en

Il setup senza opzioni shell conserva per compatibilità il default embedded. Per un'installazione esistente non rilanciare setup per sovrascrivere il descrittore: registrare la configurazione attuale, modificarne la sezione shell e usare la generazione seguente. Le credenziali rimangono nei file protetti.

Aggiornare prima il binario nativo tht: le versioni precedenti rifiutano la sezione shell. Modificare poi il descrittore e generare le proiezioni:

tht --installation /percorso/assoluto/thothii-installation.yaml installation generate

Il comando non avvia né arresta servizi. Genera anche generated/frontend/config.js, che contiene configurazione pubblica, e il relativo mount Compose. Non modificare a mano i file generati. tht start rigenera le proiezioni nel normale percorso di avvio.

Applicare il normale processo di aggiornamento dei container dell'installazione. Se si usa un launcher Compose personalizzato, deve includere la proiezione Compose generata e ricreare il frontend quando cambia la configurazione. Il fingerprint della configurazione pubblica permette a Compose di rilevare il cambio. La stessa immagine frontend supporta entrambe le modalità.

Nel percorso standard del CLI, dopo avere approvato l'aggiornamento:

tht --installation /percorso/assoluto/thothii-installation.yaml start
tht --installation /percorso/assoluto/thothii-installation.yaml status
tht --installation /percorso/assoluto/thothii-installation.yaml doctor --json

Usare start --build per una revisione di codice che richiede nuove immagini, non per la sola modifica della shell. Questo è un lifecycle dell'installazione, non un comando garantito frontend-only. Un launcher personalizzato deve conservare tutti gli override di rete, autenticazione, workspace e modelli già approvati. Non usare down --volumes. Registrare gli identificatori delle immagini prima dell'aggiornamento e conservare il descrittore precedente per il rollback.

Controllare il config.js effettivamente servito, che non deve essere memorizzato in cache. In full la route API ordinaria è /api; Omics imposta nel template il prefisso same-origin /datamart-builder/api, mantenendo le altre impostazioni.

Il file pubblico standalone deve essere equivalente a:

window.__THOTHII_CONFIG__ = {
  backendBaseUrl: "/api",
  shell: { mode: "full", defaultLocale: "en" }
};

È un risultato da controllare, non un file da mantenere a mano. In Omics il template carica /datamart-builder/config.js, conserva l'oggetto con Object.assign cambiando solo backendBaseUrl in /datamart-builder/api, poi carica gli asset dal manifest. Il config senza cache deve precedere ogni modulo React; verificare nella rete del browser l'URL finale /datamart-builder/api/me.

Accesso in parole semplici

In Omics l'utente effettua l'accesso al portale come oggi. Quando sceglie Datamart Builder, il server controlla che possa usarlo e comunica a ThothII chi è. ThothII apre l'applicazione per quella persona: non presenta un altro login e non crea una seconda sessione browser. Le password non vengono trasmesse a ThothII. Il nome e il comando Esci rimangono nell'header del portale.

Sul Mac full, ThothII presenta il proprio login locale. Dopo l'accesso mostra il nome nell'header; il menu del nome contiene il logout. Riutilizza gli utenti e la configurazione di accesso dell'installazione. Full supporta anche un'eventuale autenticazione OIDC configurata; il suo logout termina la sessione ThothII, non promette di disconnettere l'utente da tutti gli altri servizi OIDC.

Full/upstream non può terminare una sessione posseduta dal proxy e non mostra quel comando logout. Embedded non presenta mai il login ThothII, neppure per recuperare un errore di configurazione. Per un server autonomo con login/logout ThothII usare full/OIDC, non full/upstream.

I controlli server restano autorevoli. Un errore su una singola operazione non deve cancellare automaticamente l'accesso all'intera applicazione. Un rifiuto della verifica dell'utente chiude invece lo stato protetto. L'accesso viene ricontrollato anche al ritorno alla pagina e quando il collegamento eventi deve riconnettersi. Questo non equivale a una revoca istantanea di ogni connessione già aperta in altre schede.

Contratto server Omics

Il percorso corrente usa il controllo Django della capability datamart_builder.access, la subrequest nginx auth_request e gli header normalizzati X-Thoth-Principal-Issuer, X-Thoth-Principal-Subject, X-Thoth-Principal-Display-Name e X-Thoth-Is-Admin. Il browser non può scegliere queste identità: il proxy ricava gli header dal controllo server e sostituisce quelli eventualmente forniti dal client.

Mantenere il backend configurato per l'autenticazione upstream e i suoi controlli di autorizzazione. Non esporre un percorso alternativo che permetta al browser di raggiungerlo aggirando quel controllo. Non introdurre token nel documento, negli eventi UI o nella configurazione pubblica.

La guida upstream riporta i vincoli esatti: AUTH_MODE=upstream nel core, nessun auth.yaml o runtime projection contemporaneo, capability Django, quattro header obbligatori/facoltativi, percorso diretto Omics distinto dal proxy generico a due hop, origine e SSE. Non usare tht auth configure --mode oidc per «completare» l'accesso Omics già funzionante.

Come funziona l'adapter

OmicsPortalAdapter è il solo modulo frontend che conosce il documento Omics. Legge il data-lang del selettore lingua, osserva data-bs-theme e ascolta lo stato fullscreen del documento. Fornisce snapshot { locale, theme, fullscreen } al controller di shell. Non invia comandi al portale e non usa un handshake.

La pagina Omics deve continuare a esporre il selettore select.omics-language-select con la lingua renderizzata nel suo data-lang, e il tema light/dark nell'attributo di html. Il selettore lingua usa il normale form Django; non occorre convertirlo in una richiesta asincrona.

Per un altro portale, implementare la stessa sottoscrizione e selezionare il nuovo adapter nel punto di composizione. Le pagine, l'i18n e il workflow non devono acquisire riferimenti al nuovo portale. Sul lato server, il nuovo contenitore deve anche fornire un'identità verificata conforme al contratto upstream. Cambiare una classe JavaScript non sostituisce quel requisito.

Lingue e sessioni

Ci sono tre scelte distinte:

Scelta	Dove viene conservata	Cosa influenza
Lingua UI	preferenza full o stato Omics	label, form, messaggi e controlli
Lingua di interazione	interaction_language nel manifest	nuove domande, spiegazioni e scelte del modello
Lingua workspace	configurazione del workspace	documenti, descrizioni e contenuti di dominio

La creazione web acquisisce la lingua UI prima delle operazioni asincrone e la invia come interactionLanguage. Un cambio successivo non modifica quella richiesta. La ripresa legge il manifest e non usa il locale del browser come override. SQL, identificatori, valori e citazioni dei contenuti rimangono invariati.

Per sessioni precedenti senza interaction_language, la prima ripresa fissa la lingua del workspace in modo idempotente. Se il workspace era stato modificato nel frattempo, non esiste una registrazione da cui ricostruire con certezza la vecchia lingua: il criterio di compatibilità è quella disponibile alla ripresa.

Il cambio lingua di Omics ricarica la pagina. ThothII ricorda soltanto l'identificatore della sessione per utente e pagina, senza salvare una trascrizione nel browser. Il recupero riapre il pannello dei documenti; la ripresa operativa è esplicita e non avvia una generazione soltanto perché la pagina è stata ricaricata. Le bozze non inviate e le modifiche amministrative richiedono protezione dalla navigazione.

Aggiungere e verificare traduzioni

I messaggi inglesi fungono da identificatori gettext-style e fallback. I cataloghi italiani sono divisi per area per agevolarne la manutenzione. Usare useI18n() nei componenti e interpolazioni nominate, evitando concatenazioni che rendano impossibile cambiare l'ordine delle parole. Non chiamare il traduttore su SQL, testi del modello o descrizioni del workspace.

Per una nuova lingua aggiungere il catalogo, registrarlo nel risolutore e renderlo disponibile nel selettore full. Il portale deve fornire il relativo locale. La lingua delle sessioni è già esplicita e non richiede una nuova struttura del manifest. Le traduzioni dei controlli della griglia provengono dal catalogo ufficiale della stessa versione di AG Grid.

cd frontend
npm run check:i18n
npx tsc -b
npx vitest run

Il controllo dei cataloghi segnala messaggi statici mancanti, interpolazioni incompatibili e traduzioni discordanti. Non può provare da solo la copertura di tutti i messaggi dinamici: completarlo con i test delle pagine e la verifica visiva.

La build verifica anche il CSS effettivamente generato: il reset Tailwind viene limitato al mount React e ai suoi popup con selettori ordinari, senza richiedere supporto browser a @scope. Mantenere letterali le classi dei due modi della shell per conservarle durante la rimozione del CSS inutilizzato. Le griglie usano il tema CSS esistente con i token light/dark; non mescolarlo con la nuova Theming API di AG Grid.

Verifica prima del deploy server

Acquisire prima le modifiche al repository Omics

Procedura concordata il 13 settembre 2026: Mac → GitHub → server → Gitea PSD. Il Mac pubblica il branch Omics codex/thothii-embedded-shell su https://github.com/Dallavilla-Tiziano/omics_portal.git; l'operatore lo recupera dal server e lo pubblica su ssh://git@localhost:2222/aritmolab/omics_portal.git. Il secondo passaggio è un push a Gitea, non un pull. Questa scelta evita di richiedere al Mac credenziali Gitea PSD. Non cambia l'origine Gitea TYL di ThothII.

Consegna GitHub verificata il 13 settembre 2026: fca10901a73666ca257d8f4cc4b77066295c400a, che include il commit funzionale 95154e1 e la guida per il server. Per questa consegna lo SHA acquisito sul server deve coincidere esattamente. Eventuali consegne successive richiedono un nuovo SHA comunicato e approvato, non l'accettazione implicita della testa del branch.

I comandi completi sono nella guida del repository Omics. Sul server, per recuperare il branch e leggere la guida senza cambiare i file del portale in esecuzione:

cd /home/chirone/omics_portal
git status --short --branch
git fetch --no-tags https://github.com/Dallavilla-Tiziano/omics_portal.git \
  refs/heads/codex/thothii-embedded-shell:refs/remotes/github-relay/codex/thothii-embedded-shell
git rev-parse refs/remotes/github-relay/codex/thothii-embedded-shell
git show refs/remotes/github-relay/codex/thothii-embedded-shell:docs/thothii-integration.md

Confrontare lo SHA con la consegna dal Mac prima di procedere con il push documentato nella guida. Non usare git pull nel checkout condiviso né git push origin: quest'ultimo può avere due destinazioni. Non cambiare master o riavviare Omics durante il trasferimento. L'integrazione e il deploy richiedono una successiva approvazione, con revisione/immagini di rollback registrate e rilascio coordinato con ThothII embedded/upstream.

Dopo il confronto positivo con fca10901a73666ca257d8f4cc4b77066295c400a, il trasferimento verso Gitea si completa sempre dal repository Omics sul server con:

cd /home/chirone/omics_portal
git ls-remote ssh://git@localhost:2222/aritmolab/omics_portal.git \
  HEAD refs/heads/codex/thothii-embedded-shell
git push ssh://git@localhost:2222/aritmolab/omics_portal.git \
  refs/remotes/github-relay/codex/thothii-embedded-shell:refs/heads/codex/thothii-embedded-shell
git ls-remote ssh://git@localhost:2222/aritmolab/omics_portal.git \
  refs/heads/codex/thothii-embedded-shell
git status --short --branch
git rev-parse HEAD

Lo SHA Gitea deve coincidere; branch, HEAD e modifiche del checkout devono rimanere quelli registrati prima del fetch. Se diverge o il push viene rifiutato, fermarsi senza force push, reset, modifica di credenziali o merge improvvisato. Questo passaggio non pubblica ThothII, non cambia master e non fa deploy.

Preparare il rilascio coordinato

1. Registrare SHA approvati di entrambi i repository, immagini precedenti, descriptor ThothII, file Compose/override e progetto realmente in uso. La testa del branch di lavoro non è automaticamente una revisione approvata di produzione.

2. In un checkout di revisione separato, integrare Omics con il branch di rilascio concordato. Non fare merge nel checkout operativo con modifiche altrui. I file Omics da includere sono template Datamart Builder/topbar/base, asset fullscreen e cataloghi Django del branch; conservare la verifica server esistente in kokoro/datamart_catalog_views.py e le location Nginx protette.

3. Eseguire dal checkout Omics i test isolati, non i test contro il database operativo:

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

4. Predisporre il descrittore ThothII embedded e il core upstream secondo la guida. Verificare che Nginx Omics possa raggiungere gli alias privati thothii-core:8787 e thothii-frontend:8080 e che non esista un ingresso non protetto al core. Non sovrascrivere rete, mount o autenticazione usando il Compose locale del Mac.

5. Solo dopo il gate operatore, applicare le revisioni approvate seguendo il lifecycle dei due progetti. In Omics i servizi sono web e nginx: includere nel rebuild template, statici e cataloghi, mantenendo tutti gli override del server. Verificare la configurazione Nginx con nginx -t nel servizio e lo stato di entrambi. Non inventare opzioni Compose/progetto: usare quelle registrate al punto 1. Gli entrypoint del portale possono avere altri effetti operativi: questa modifica non richiede nuove migrazioni DB, ma non autorizza a bypassare i controlli del suo rilascio.

6. Dopo l'aggiornamento del frontend, attendere la cache manifest Django (30 s) oppure usare l'invalidazione prevista dal portale; ricaricare e controllare config/asset/prefisso API prima di giudicare il risultato.

7. Compilare la matrice seguente. In caso di errore ripristinare revisioni, immagini e configurazioni registrate, senza cancellare volumi. Il rollback deve conservare una coppia compatibile di template Omics e frontend ThothII.

La consegna GitHub è verificata; il push Gitea PSD e il deploy del nuovo branch Omics rimangono da confermare dall'operatore. I test locali non attestano lo stato attuale del server remoto.

Accettazione dell'integrazione

Usare la matrice completa full/embedded e autenticazione, registrando per ogni prova revisione, ambiente e risultato. Non spuntare i casi IdP/Omics reali soltanto perché passano i test con risposte simulate.

Provare l'apertura dal menu Omics con un utente autorizzato e uno senza accesso; verificare assenza di un secondo login e di header ThothII, italiano/inglese già selezionati prima dell'apertura, tema, fullscreen e uscita con Esc. Ripetere con un menu o un form aperto, una bozza non inviata e una sessione esistente.

Verificare perdita dell'accesso, ritorno alla scheda e riconnessione degli eventi; distinguere questi casi dal rifiuto di una sola operazione. Controllare che una ripresa conservi la lingua salvata e che il reload non avvii una nuova generazione. Eseguire i test Omics nel suo ambiente Docker e includere gli aggiornamenti dei template, degli asset e dei cataloghi Django nel suo normale rebuild.

La verifica del codice e i test locali non costituiscono un deploy sul server di produzione. Usare il normale processo di rilascio per applicare entrambe le revisioni e annotare immagini, descrittore e revisioni realmente installate.