diff --git a/AGENTS.md b/AGENTS.md index f397b6f7..04ee90be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -102,6 +102,9 @@ frontend (React/SSE) → backend (Fastify) → pi --mode rpc → tht/harness → model interaction uses the session manifest's immutable `interaction_language`. Workspace content, SQL, and identifiers remain unchanged. For shell modes, portal integration, or translations, read `docs/operations/shell-and-localization.md`. +- **Server deployment:** for the coordinated ThothII/Omics upgrade, follow + `docs/operations/server-codex-handoff.md`; it supersedes earlier Omics delivery + instructions. Omics source integration uses GitHub with no repository relay prerequisite. - **Server identity:** for portal login/logout, proxy headers, or Omics deploy, read `docs/install/authentication-upstream.md` before changing authentication. Omics uses embedded/upstream, not a second ThothII OIDC login. Full/embedded rendering diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md index 4cd75b16..66502815 100644 --- a/PROJECT_STATE.md +++ b/PROJECT_STATE.md @@ -29,15 +29,15 @@ independent reviews, local browser checks and rollback details. Current rendering architecture is in `docs/architecture/application-shell.md`; the exact portal identity/proxy contract is in `docs/install/authentication-upstream.md`. -`docs/operations/shell-and-localization.md` is the configuration and coordinated -Omics delivery/deploy runbook, including server-side fetch GitHub → explicit push -Gitea PSD from `/home/chirone/omics_portal`. The acceptance matrix is +`docs/operations/server-codex-handoff.md` is the current server delivery/deploy +runbook, including Omics source integration from GitHub, configuration, tests and +rollback. It supersedes the earlier Omics repository-relay instructions. The acceptance matrix is `docs/testing/authentication-manual-acceptance.md`. README, documentation navigation, user/installation/authentication guides and descriptor examples point to these paths. Local examples explicitly use full/en; the projected server example is for standalone OIDC, not Omics upstream. No runtime configuration or deployment -was changed by this documentation pass. Closing/merging the branch and actual -PSD acceptance remain separate, unperformed steps. +was changed by that documentation pass. The 2026-09-14 delivery is prepared for +promotion to main; the actual merge is recorded in Git. PSD acceptance remains pending. ### Navigation readiness and session accordions — 2026-09-13 @@ -64,27 +64,23 @@ Core, catalog, Qdrant and embedding containers were not changed. The prior frontend image is retained as `thothii-frontend:before-single-session-accordion-20260914` for rollback. -### Agreed Omics delivery route — 2026-09-13 +### Current Omics delivery and server handoff — 2026-09-14 -The owner approved GitHub as an intermediate transport for Omics: publish only -`codex/thothii-embedded-shell` from the Mac to -`https://github.com/Dallavilla-Tiziano/omics_portal.git`. The operator then works -in `/home/chirone/omics_portal` on the PSD server, fetches that branch without -changing the shared checkout, verifies the delivered SHA, and pushes only that -branch to `ssh://git@localhost:2222/aritmolab/omics_portal.git` using existing -server credentials. Do not require a PSD Gitea token on the Mac to continue. -Do not use the server's dual-push `origin` or merge into its current branch as -part of transport. Production integration/rebuild is a separate operator gate. -ThothII still uses its canonical TYL Gitea; this exception is for Omics only. -Exact commands and the handoff are linked from -`docs/operations/shell-and-localization.md`; the full server procedure lives in -Omics `docs/thothii-integration.md`. Never report the PSD push or production -deployment as complete until the operator supplies confirmation. +The owner corrected the delivery requirement: Omics is obtained from GitHub, +not relayed to another repository as part of this deployment. Any optional +server-side repository copy is solely the owner's separate concern. This +supersedes the 2026-09-13 relay agreement, including historical delivery notes +in the Omics branch. Do not make another remote publication a prerequisite. -GitHub delivery verified on 2026-09-13 at -`fca10901a73666ca257d8f4cc4b77066295c400a` (functional commit `95154e1` plus -the server relay runbook). GitHub `master` remains `aff7581`. The operator's -PSD Gitea push and production deployment are still pending. +GitHub branch `codex/thothii-embedded-shell` at +`https://github.com/Dallavilla-Tiziano/omics_portal.git` was reverified at +`fca10901a73666ca257d8f4cc4b77066295c400a` (functional commit `95154e1`). +The server operator integrates it with the current code in the confirmed Omics +checkout, normally `/home/chirone/omics_portal`, preserving later server changes. +`docs/operations/server-codex-handoff.md` is the authoritative ordered procedure: +inventory, source verification, native CLI and installation projections, +embedded/upstream auth, Omics templates/static assets/proxy, coordinated rollout, +acceptance and rollback. Server deployment and real IdP acceptance remain pending. ## Current product shape diff --git a/README.md b/README.md index ed976785..e05d2406 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,10 @@ Omics uses embedded/upstream with its existing login, and a standalone server can use full/OIDC. See [rendering architecture](docs/architecture/application-shell.md) and [configuration, Omics delivery and deploy](docs/operations/shell-and-localization.md). +For the current server upgrade with Omics Portal, follow the ordered +[Codex server handoff](docs/operations/server-codex-handoff.md), including source +integration, embedded/upstream configuration, coordinated rollout and rollback. + Local/OIDC authentication is configured through the host CLI `tht`; portal authentication is established by the trusted server proxy. See the [local guide](docs/install/authentication-local.md), diff --git a/docs/index.md b/docs/index.md index 0950cbe2..c3399318 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,6 +8,7 @@ Start with the path that matches the work you need to do: | I need to… | Start here | | --- | --- | | Install or operate one instance | [Install and first start](install/first-start.md) | +| Upgrade the server and integrate Omics Portal | [Codex server handoff](operations/server-codex-handoff.md) | | Choose full/embedded and configure the shell | [Shell and localization](operations/shell-and-localization.md) | | Reuse an authenticated server portal without a second login | [Upstream authentication](install/authentication-upstream.md) | | Understand how the two renderings share the same application | [Rendering architecture](architecture/application-shell.md) | diff --git a/docs/operations/server-codex-handoff.md b/docs/operations/server-codex-handoff.md new file mode 100644 index 00000000..fc330c44 --- /dev/null +++ b/docs/operations/server-codex-handoff.md @@ -0,0 +1,378 @@ +# Consegna a Codex sul server: ThothII e Omics Portal + +Revisione: **14 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 su `main` e includere almeno +`bdcd8fcd28f3011471d77224db9c3f5baf227995` e questo documento. Registra anche lo +SHA effettivo di `main`, che include il commit di consegna e il merge successivi: + +```bash +git status --short --branch +git rev-parse HEAD +git merge-base --is-ancestor bdcd8fcd28f3011471d77224db9c3f5baf227995 HEAD +``` + +Se il controllo fallisce, completa l'acquisizione della revisione approvata +prima di toccare l'installazione. Non ricostruire a mano le singole modifiche UI: +questa revisione 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. diff --git a/docs/operations/server-upgrade-gitea-workspace-v2.md b/docs/operations/server-upgrade-gitea-workspace-v2.md index 10b4e6bc..df19af91 100644 --- a/docs/operations/server-upgrade-gitea-workspace-v2.md +++ b/docs/operations/server-upgrade-gitea-workspace-v2.md @@ -27,12 +27,9 @@ la `origin/main` approvata dall'operatore. ## Regole non negoziabili -- Per le modifiche al portale Omics seguire prima la - [consegna via GitHub e server verso Gitea PSD](shell-and-localization.md#acquisire-prima-le-modifiche-al-repository-omics). - L'operatore lavora in `/home/chirone/omics_portal`: fetch del branch dedicato - da GitHub, verifica SHA, push esplicito a Gitea. Il trasferimento non modifica - il checkout di produzione e non autorizza un deploy; non cercare credenziali - Gitea PSD sul Mac per aggirare questa procedura concordata. +- Per il rilascio Omics seguire la [consegna corrente a Codex sul server](server-codex-handoff.md). + Acquisire il branch dedicato da GitHub, verificare SHA e integrarlo con i + progressi del server; nessuna replica del repository è richiesta. - Eseguire prima l'intero inventario in sola lettura e consegnarlo all'operatore. - Non stampare mai password, token, chiavi private, cookie, file `.env` o contenuti dei Docker secret. Nei report sono ammessi solo percorsi, nomi delle variabili e valori non segreti. diff --git a/docs/operations/shell-and-localization.md b/docs/operations/shell-and-localization.md index bbdb1a9e..880ab1c6 100644 --- a/docs/operations/shell-and-localization.md +++ b/docs/operations/shell-and-localization.md @@ -239,60 +239,23 @@ CSS esistente con i token light/dark; non mescolarlo con la nuova Theming API di ### 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. +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. -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. +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. -I comandi completi sono nella -[guida del repository Omics](https://github.com/Dallavilla-Tiziano/omics_portal/blob/codex/thothii-embedded-shell/docs/thothii-integration.md#consegna-via-github-e-pubblicazione-su-gitea-psd). -Sul server, per recuperare il branch e leggere la guida senza cambiare i file -del portale in esecuzione: - -```bash -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: - -```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. +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 @@ -330,8 +293,8 @@ Questo passaggio non pubblica ThothII, non cambia `master` e non fa deploy. 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 +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 diff --git a/mkdocs.yml b/mkdocs.yml index 8799df16..7417cc9e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,6 +54,7 @@ nav: - Authentik: install/authentik.md - Workspace operations: operations/workspaces.md - Shell and localization: operations/shell-and-localization.md + - Codex server handoff: operations/server-codex-handoff.md - Full shell verification: reports/2026-09-13-full-shell-implementation.md - Local sensitivity analysis: operations/sensitivity-analysis.md - Pi model configuration: general/pi-configuration.md