docs: document full and embedded rendering with server authentication
This commit is contained in:
Codex
@@ -1,7 +1,11 @@
|
||||
# Shell, autenticazione e lingue
|
||||
|
||||
Questa guida accompagna la [specifica approvata](../plans/2026-09-13-full-shell-spec.md)
|
||||
e il [contratto Portal Shell Adapter](../contracts/portal-shell-adapter-v1.md).
|
||||
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
|
||||
|
||||
@@ -9,6 +13,16 @@ La modalità della shell è indipendente dal profilo di distribuzione e dal meto
|
||||
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
|
||||
@@ -22,6 +36,7 @@ Per il server Omics:
|
||||
```yaml
|
||||
shell:
|
||||
mode: embedded
|
||||
defaultLocale: en
|
||||
adapter: omics-portal
|
||||
```
|
||||
|
||||
@@ -36,6 +51,17 @@ 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:
|
||||
|
||||
@@ -54,10 +80,40 @@ 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
|
||||
@@ -72,6 +128,11 @@ la configurazione di accesso dell'installazione. Full supporta anche un'eventual
|
||||
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
|
||||
@@ -93,6 +154,12 @@ 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.
|
||||
@@ -206,8 +273,73 @@ documentato nella guida. Non usare `git pull` nel checkout condiviso né
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```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 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](../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
|
||||
|
||||
Reference in New Issue
Block a user