320 lines
16 KiB
Markdown
320 lines
16 KiB
Markdown
# Shell, autenticazione e lingue
|
|
|
|
Questa è la procedura operativa del rendering corrente. Leggerla insieme a
|
|
[architettura full/embedded](../architecture/application-shell.md),
|
|
[autenticazione upstream](../install/authentication-upstream.md) e
|
|
[contratto PortalAdapter](../contracts/portal-shell-adapter-v1.md).
|
|
La [specifica approvata](../plans/2026-09-13-full-shell-spec.md) 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:
|
|
|
|
```yaml
|
|
shell:
|
|
mode: full
|
|
defaultLocale: en
|
|
```
|
|
|
|
Per il server Omics:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```javascript
|
|
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](../install/authentication-upstream.md) 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.
|
|
|
|
```bash
|
|
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 aggiornata il 14 settembre 2026: acquisire il codice Omics da GitHub
|
|
e integrarlo con il codice operativo del server. Non è richiesta alcuna replica
|
|
del repository su altri servizi; l'eventuale copia è un'attività distinta del
|
|
proprietario. Questa indicazione sostituisce le precedenti note di trasporto,
|
|
anche se ancora presenti nei documenti storici del branch Omics.
|
|
|
|
La [consegna corrente a Codex sul server](server-codex-handoff.md) contiene i
|
|
comandi esatti di acquisizione, gli SHA, i file da adeguare, la configurazione
|
|
embedded/upstream, i test, i gate di rilascio e il rollback. Usarla come procedura
|
|
ordinata per l'aggiornamento; le sezioni qui sotto restano il riepilogo tecnico.
|
|
|
|
Consegna GitHub riverificata: branch `codex/thothii-embedded-shell` di
|
|
`https://github.com/Dallavilla-Tiziano/omics_portal.git`, SHA
|
|
`fca10901a73666ca257d8f4cc4b77066295c400a`, incluso il commit funzionale
|
|
`95154e179144e2453b37ef2a63a65d6f377e4cf8`. Il pull di ThothII non aggiorna
|
|
Omics: il checkout del portale, normalmente `/home/chirone/omics_portal`, va
|
|
verificato e integrato separatamente preservando le modifiche successive del server.
|
|
|
|
### 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:
|
|
|
|
```bash
|
|
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 deploy della revisione integrata
|
|
Omics rimane 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](../testing/authentication-manual-acceptance.md),
|
|
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.
|