docs: plan PSD server deployment program

This commit is contained in:
2026-08-20 00:57:47 +02:00
parent 3fd177b6c4
commit 21caaa22e3
11 changed files with 2154 additions and 2 deletions
@@ -0,0 +1,98 @@
# PSD Server Project A — Acceptance Report
> Template only. Store detailed/raw evidence in the protected server evidence root. This report
> must not contain passwords, tokens, cookies, keys, hashes of passwords, secret-file contents,
> raw claims, patient-identifying data, or unbounded logs.
## Decision
- Result: `PROJECT_A_PASS` / `PROJECT_A_FAIL` / `PROJECT_A_PENDING`
- Decision timestamp UTC:
- Owner/reviewer:
- Protected evidence path:
- Evidence manifest SHA-256:
## Frozen identities
- ThothII source SHA:
- Plan source SHA:
- Workspace previous SHA:
- Workspace multi-transport SHA:
- Mac REST validation result/evidence reference:
- Native `tht` version/build identity:
- Core image ID/digest:
- Frontend image ID/digest:
- Qdrant image digest:
- Ollama image digest:
- Pi version/provider/model/thinking:
## Survey and legacy recovery
- Survey result/digest:
- Legacy source/image identity:
- Legacy backup location/checksum reference:
- Legacy restart recipe verified: PASS/FAIL
- Legacy stack stopped without deletion: PASS/FAIL
- Production route closed: PASS/FAIL
## New installation
- Installation descriptor path:
- Compose project:
- Frontend loopback/private origin:
- Optional private endpoint used: yes/no
- Optional allowlist positive/negative result:
- Service health result:
- Doctor result:
- Pi result:
- Listener-boundary result:
## Authentication
- Mode: local
- Admin/user separation:
- Wrong-password generic failure:
- Disable/enable:
- Password/role/logout-all invalidation:
- Remembered restart:
- Logout:
- CSRF/cross-origin rejection:
- Manual guide result and reviewer:
## Workspace and data plane
- Workspace ID/revision:
- Server transport: postgres_direct
- Mac transport remains rest_api: PASS/FAIL
- Supabase database name:
- DWH schema: datawarehouse
- Read-only role proof reference:
- DWH connection diagnostics:
- Qdrant collection contract:
- Ollama model/dimensions:
- Preprocess first run ID/result:
- FK review digest/result:
- Schema point count:
- Evidence point/chunk count:
- Preprocess idempotency result:
- Effective configuration identity:
## F1-F8 session
- Approved sanitized question reference:
- Session ID:
- Owner identity type: local ordinary user
- Resume tested:
- F1-F8 result:
- Finalized:
- Final SQL read-only validation:
- Persisted artifact/decision inventory:
- No patient-identifying evidence retained: PASS/FAIL
## Rollback and hygiene
- New-installation backup/checksum reference:
- Legacy rollback remains available:
- Secret scan result:
- Unrelated failures or pending items:
- Reason for final decision:
@@ -0,0 +1,108 @@
# PSD Server Project B — Acceptance Report
> Template only. Store raw Authentik exports, database backups, browser traces, and server topology
> only in protected server storage. Never retain passwords, provider/client secrets, API tokens,
> cookies, raw claims, callback query strings, private keys, patient-identifying data, or unbounded
> logs in this report.
## Decision
- Result: `PROJECT_B_PASS` / `PROJECT_B_FAIL` / `PROJECT_B_PENDING`
- Decision timestamp UTC:
- Owner/reviewer:
- Protected evidence path:
- Evidence manifest SHA-256:
- Accepted Project A report digest:
## Frozen candidate
- ThothII source SHA:
- Workspace SHA:
- Core/frontend image identities:
- Qdrant/Ollama image identities:
- Pi provider/model:
- Public origin:
- Aritmolab source/deployment revision:
## Authentik
- Installed version:
- Pre-change export reference/checksum:
- Application name/ID:
- Provider name/ID:
- Issuer:
- Callback path verified:
- Grant types/scopes verified:
- Direct groups claim shape verified:
- User group name/ID:
- Admin group name/ID:
- Group-catalog service account name/ID:
- Least-privilege result:
- `auth check --json` result:
- Interactive device check: PASS/FAIL/PENDING
- No secret/raw claim in evidence: PASS/FAIL
## Supabase session storage
- Existing database name:
- Session schema: thoth_sessions
- Backup reference/checksum:
- Migration result (`pending=[]`, `drifted=[]`):
- Migration idempotency:
- Runtime role security/RLS result:
- Migrator absent from core:
- PostgREST exposed schemas proof:
- `thoth_sessions` not REST-exposed: PASS/FAIL
- DWH `datawarehouse` privileges unchanged: PASS/FAIL
## Nginx, TLS, load balancer, and Aritmolab
- Nginx configuration file/revision:
- `nginx -t` result:
- Certificate subject/SAN/expiry metadata:
- Certificate trust result:
- Load-balancer route/health result:
- Same-origin API/callback result:
- SSE unbuffered result:
- No double `auth_request`: PASS/FAIL
- Sidebar source/link result:
- Other virtual hosts unchanged: PASS/FAIL
## Human SSO and authorization
- Aritmolab login → sidebar → ThothII without second credential prompt:
- Ordinary user permissions:
- Administrator permissions:
- No-role user result:
- Extra unrelated group result:
- Missing/malformed group negative result:
- Forged-header result:
- ThothII logout result:
- Authentik SSO session behavior documented:
- Provider/catalog controlled failure and recovery:
- Manual guide result and reviewer:
## OIDC F1-F8 session and ownership
- Approved sanitized question reference:
- Session ID:
- OIDC principal reference (non-identifying):
- F1-F8/final SQL result:
- PostgreSQL manifest/artifact/decision persistence:
- Resume/restart result:
- Cross-user isolation result:
- Admin cross-user result:
- Chat/SSE ephemeral boundary:
## Rollback, cleanup, and hygiene
- Ingress-first rollback rehearsal:
- Project A protected configuration available:
- Authentik disable plan verified:
- Additive schema rollback boundary verified:
- Project A temporary endpoint removed:
- Legacy stack stopped/unexposed:
- Core/Qdrant/Ollama private:
- Secret scan result:
- Unrelated failures or pending items:
- Reason for final decision:
@@ -0,0 +1,151 @@
# PSD Server — Survey Report
> Template only. The completed report and raw inventory remain in protected server storage. Do not
> include passwords, tokens, cookies, private keys, password hashes, raw claims, full container
> environments, patient-identifying data, or unbounded logs.
## Decision
- Result: `SURVEY_GO` / `SURVEY_NO_GO`
- Timestamp UTC:
- Operator:
- Protected evidence path:
- Report SHA-256:
- Blocking unknowns:
## Host
- OS/version/kernel:
- Architecture:
- Docker/Compose versions:
- CPU/RAM/free disk:
- Approved service UID/GID:
- Local terminal/CyberArk constraints:
## Legacy ThothII
- Source path/SHA/dirty state:
- Compose/controller path and project:
- Services/images:
- Published ports:
- Networks:
- Volumes/binds:
- Data/config/secret reference paths:
- Current health:
- Active sessions/users:
- Recovery/maintenance state:
- Backup procedure and owner:
- Exact stop/start commands:
## New installation roots
- Adjacent source root:
- Operator root:
- Secret root:
- Data root:
- Pi-state root:
- Workspace-registry root:
- Backup root:
- Protected evidence root:
- Port reserved for Project A:
## Nginx, TLS, and load balancer
- Nginx version/config owner:
- Relevant virtual-host/include files:
- Current ThothII upstream:
- Forwarded headers/SSE behavior:
- Certificate subject/SAN/issuer/expiry:
- Certificate generation/renewal owner:
- Load-balancer owner/config surface:
- Health check/TLS boundary/source addresses:
- Temporary hostname allowlist possible: yes/no
- Exact reload/rollback procedure:
## Aritmolab
- Public origin observed:
- Source/deployment path and SHA:
- Compose/network identity:
- Sidebar file/line/link target:
- Historical `.it`/`.com` discrepancy resolved as:
- Build/test/deploy procedure:
- Configuration owner:
## Authentik
- Installed version/image:
- Deployment path/services:
- Base URL/issuer conventions:
- Existing Aritmolab application/provider pattern:
- Groups relevant to ThothII:
- Credential reference paths and usability:
- Export/backup procedure:
- API/OpenAPI version:
- Required human help:
## Supabase/PostgreSQL
- Existing database name:
- PostgreSQL/pooler/PostgREST components:
- Direct container-to-database route:
- TLS mode/CA reference:
- Existing schemas:
- Existing `thoth_sessions` state:
- PostgREST exposed schemas:
- Backup/restore mechanism:
- Proposed runtime/migrator role names:
- Role-creation owner:
## PSD DWH
- Database/schema:
- Direct host/port from core:
- Runtime role reference:
- Read-only grant proof result:
- TLS requirements:
- REST binding retained for Mac:
## Workspace Git
- Remote/branch/access:
- Current main SHA:
- Server deploy-key scope:
- Descriptor schema/transports:
- Evidence/annotations state:
- Curator with push authority:
## Pi, LLM, Qdrant, and Ollama
- Pi version/provider/model/thinking:
- Credential reference:
- LLM endpoint reachability:
- Qdrant/Ollama image architecture support:
- Capacity assessment:
## Topology
Describe the observed final flow and every trust boundary. Reference a protected diagram if the
topology itself is considered sensitive.
## Intended changes by owner
| Owner/component | Exact files/objects | Project | Rollback |
|---|---|---|---|
| New ThothII | | A/B | |
| Workspace curator | | A | |
| Nginx | | A optional/B | |
| Load balancer | | A optional/B | |
| Aritmolab | | B | |
| Authentik | | B | |
| Supabase | | B | |
## GO/NO-GO rationale
- Verified old-stack rollback:
- Verified secret custody:
- Verified read-only DWH:
- Verified configuration owners:
- Verified resources:
- Unresolved risks:
- Final rationale:
+166
View File
@@ -0,0 +1,166 @@
# Progetto A PSD — collaudo manuale
Questo documento guida il collaudo umano del nuovo ThothII sul server con autenticazione locale.
Non sostituisce i controlli automatici del piano. Compilarlo soltanto dopo che Sol ha dichiarato
verdi installazione, workspace, DWH, Qdrant, Ollama e preprocessing.
## Regole
- Eseguire i comandi dal terminale locale del server; non usare tunnel SSH.
- Non copiare nel rapporto password, cookie, token, chiavi, hash, stringhe di connessione o righe di
log che li contengano.
- Usare un amministratore locale e un utente ordinario creati appositamente.
- Non effettuare più tentativi di password errata del necessario: il login applica rate limiting.
- Per ogni prova segnare `PASS`, `FAIL` o `PENDING`, con una nota breve e non sensibile.
- Un solo `FAIL` obbligatorio impedisce di avviare il Progetto B.
## Dati iniziali
| Campo | Valore redatto |
|---|---|
| Data/ora UTC | |
| SHA ThothII | |
| SHA workspace | |
| Installation descriptor | percorso protetto, senza contenuto |
| Origine di test | loopback oppure hostname privato |
| Endpoint temporaneo usato | sì/no |
| ID domanda di prova approvata | |
| Operatore | |
## 1. Stato generale
Eseguire:
```bash
THT_BIN=<percorso-tht>
INSTALLATION=<percorso-assoluto-thothii-installation.yaml>
"$THT_BIN" --installation "$INSTALLATION" status
"$THT_BIN" --installation "$INSTALLATION" doctor --json
"$THT_BIN" --installation "$INSTALLATION" auth check --json
"$THT_BIN" --installation "$INSTALLATION" pi test
```
| Prova | Risultato atteso | Esito | Note |
|---|---|---|---|
| Stato servizi | frontend, core, qdrant ed embedding sani; initializer completato | | |
| Doctor | tutti i controlli obbligatori passano | | |
| Autenticazione | modalità `local`, configurazione pronta | | |
| Pi | provider e modello rispondono | | |
| Secret hygiene | nessun secret nell’output | | |
## 2. Confine di rete
Dal terminale controllare i listener e la configurazione renderizzata secondo il piano.
| Prova | Risultato atteso | Esito | Note |
|---|---|---|---|
| Frontend | pubblicato solo su loopback o tramite endpoint privato approvato | | |
| Core | nessuna porta host pubblica | | |
| Qdrant | nessuna porta host pubblica nel profilo server | | |
| Ollama | nessuna porta host pubblica | | |
| URL produzione | non raggiunge il nuovo stack | | |
| Endpoint privato, se usato | sorgente autorizzata ammessa | | |
| Endpoint privato, se usato | sorgente non autorizzata respinta prima di ThothII | | |
Se non esiste un endpoint privato, usare il browser headless/API sul server. Non segnare come
eseguite prove browser che non sono state realmente svolte.
## 3. Autenticazione locale
Eseguire tramite frontend/browser quando disponibile; altrimenti usare richieste same-origin dal
terminale, conservando cookie e password soltanto in file temporanei mode `0600`, poi eliminandoli.
| Prova | Azione | Risultato atteso | Esito | Note |
|---|---|---|---|---|
| Accesso anonimo | aprire pagina/API protetta | appare login oppure HTTP 401 | | |
| Password errata | un tentativo con utente valido | errore generico; nessun dettaglio account | | |
| Utente ordinario | login corretto | accesso alle sessioni | | |
| Confine ruoli | aprire Pi Management/amministrazione | negato o non visibile | | |
| Logout | uscire e ricaricare | sessione rifiutata, nuovo login richiesto | | |
| Amministratore | login corretto | funzioni amministrative previste disponibili | | |
| Disabilitazione | Sol disabilita l’utente di prova | login rifiutato genericamente | | |
| Riabilitazione | Sol riabilita l’utente | login nuovamente possibile | | |
| Invalidazione | cambio password/ruolo o `logout-all` | vecchia sessione non più valida | | |
| Remember me | login persistente, riavvio core | sessione ancora valida entro TTL | | |
| CSRF | mutazione senza token corretto | richiesta respinta | | |
Non disabilitare o demansionare l’ultimo amministratore abilitato.
## 4. Workspace e DWH
Eseguire:
```bash
"$THT_BIN" --installation "$INSTALLATION" \
workspace inspect --workspace psd-clinical --json
"$THT_BIN" --installation "$INSTALLATION" \
workspace vector inspect --workspace psd-clinical --json
```
| Prova | Risultato atteso | Esito | Note |
|---|---|---|---|
| Revisione Git | coincide con lo SHA approvato | | |
| Trasporto server | `postgres_direct` | | |
| Database/schema | database Supabase rilevato, schema `datawarehouse` | | |
| Utente DWH | read-only dimostrato dai grant | | |
| Workspace Mac | prova separata conferma ancora `rest_api` | | |
| Qdrant | 1024 dimensioni, cosine, indici payload richiesti | | |
| Ollama | `qwen3-embedding:0.6b` | | |
| Evidence | corpus Git attivo alla stessa revisione | | |
## 5. Preprocessing e idempotenza
Esaminare i due risultati consecutivi del preprocessing prodotti da Sol.
| Prova | Risultato atteso | Esito | Note |
|---|---|---|---|
| Introspezione DWH | completata senza scritture cliniche | | |
| Annotazioni FK | revisione umana registrata e legata al digest corretto | | |
| Schema index | record presenti con workspace revision | | |
| Evidence index | documenti/chunk presenti con workspace revision | | |
| Seconda esecuzione | nessun duplicato; contenuti invariati riconosciuti | | |
| Identità effettiva | invariata tra i due run | | |
## 6. Sessione completa F1–F8
Usare una domanda innocua approvata, senza identificativi reali di pazienti.
| Fase | Controllo manuale | Esito | Note |
|---|---|---|---|
| F1 | domanda compresa/disambiguata correttamente | | |
| F2 | concetti e contesto coerenti | | |
| F3 | tabelle candidate ragionevoli | | |
| F4 | colonne/join curati e confermati | | |
| F5 | piano CTE comprensibile | | |
| F6 | ogni CTE testata e approvata | | |
| F7 | SQL finale read-only e validato | | |
| F8 | conclusione, memoria e riepilogo coerenti | | |
Durante una fase intermedia chiudere/riprendere la sessione una volta. Il resume deve tornare
all’ultima fase incompleta senza creare una nuova domanda.
Verificare infine:
| Prova | Risultato atteso | Esito | Note |
|---|---|---|---|
| Stato | sessione `finalized` | | |
| SQL | solo lettura; validazione DWH verde | | |
| Artefatti | manifest, question, schema linking, Evidence, CTE, SQL, validation presenti | | |
| Decisioni | gate registrati nel ledger | | |
| Persistenza | artefatti leggibili dopo riavvio | | |
| Chat/SSE | non richiesti come persistenza | | |
## 7. Decisione
| Gate | Esito |
|---|---|
| Tutti i controlli obbligatori PASS | |
| Nessun secret raccolto | |
| Rollback vecchio stack ancora disponibile | |
| Progetto B autorizzabile | |
Decisione finale: `PROJECT_A_PASS` / `PROJECT_A_FAIL` / `PROJECT_A_PENDING`
Revisore e data: ______________________________________
Motivazione sintetica: ______________________________________
+131
View File
@@ -0,0 +1,131 @@
# Progetto B PSD — collaudo manuale Authentik e Aritmolab
Questo documento verifica il percorso finale di produzione. Si esegue soltanto dopo il PASS del
Progetto A e dopo che Sol ha completato i preflight Authentik, Supabase, Nginx e bilanciatore.
## Regole
- Usare identità di prova approvate: una ordinaria, una amministrativa e, se disponibile, una senza
gruppi ThothII.
- Non acquisire token, cookie, password, chiavi private, claim completi o trace browser contenenti
URL di callback con parametri.
- Partire dalla home reale di Aritmolab, non da un URL interno di ThothII.
- Segnare `PASS`, `FAIL` o `PENDING`; non dedurre il PASS da test automatici.
## Dati iniziali
| Campo | Valore redatto |
|---|---|
| Data/ora UTC | |
| SHA ThothII/workspace | |
| Origine pubblica | |
| SHA/revisione Aritmolab | |
| Nome/ID applicazione Authentik | non inserire secret |
| Database Supabase | |
| Schema sessioni | `thoth_sessions` |
| Operatore/revisore | |
## 1. TLS, routing e pagina iniziale
| Prova | Azione | Risultato atteso | Esito | Note |
|---|---|---|---|---|
| HTTP | aprire origine in HTTP | redirect a HTTPS | | |
| Certificato | ispezionare il lucchetto/catena | hostname corretto, nessun warning | | |
| Home Aritmolab | aprire URL ufficiale | pagina disponibile | | |
| Sidebar | individuare ThothII | link presente come prima | | |
| Destinazione | aprire il link | nuovo frontend ThothII | | |
| API | caricare l’app | nessun 502/404 o mixed content | | |
| SSE | avviare attività modello | aggiornamenti continui, niente buffering evidente | | |
## 2. Single sign-on
Chiudere ogni precedente sessione di test secondo la procedura concordata. Accedere ad Aritmolab
con l’identità ordinaria, quindi aprire ThothII dalla sidebar.
| Prova | Risultato atteso | Esito | Note |
|---|---|---|---|
| Primo login | Authentik autentica l’utente | | |
| Passaggio sidebar | nessuna seconda richiesta di credenziali | | |
| Callback | ritorno all’origine pubblica ThothII | | |
| Identità | nome visualizzato coerente, senza dati grezzi del token | | |
| Browser storage | nessun access/id token in Local/Session Storage | | |
| Cookie | cookie ThothII HttpOnly/Secure/SameSite secondo configurazione | | |
Non copiare il valore del cookie nel rapporto.
## 3. Ruoli e autorizzazione
| Identità/caso | Risultato atteso | Esito | Note |
|---|---|---|---|
| Gruppo utente | può creare, leggere e gestire le proprie sessioni | | |
| Gruppo utente | Pi Management e funzioni admin negate con 403/non visibili | | |
| Gruppo admin | funzioni amministrative documentate disponibili | | |
| Nessun gruppo mappato | autenticato ma operazioni protette negate | | |
| Gruppo estraneo aggiuntivo | nessun cambiamento e nessun warning | | |
| Header identità forgiato | nessun privilegio aggiuntivo | | |
Le prove su claim mancante/malformato possono essere eseguite da Sol con un’identità/provider di
test controllato. Il revisore verifica soltanto esito HTTP generico e report redatto, mai il token.
## 4. Logout e riavvio
| Prova | Azione | Risultato atteso | Esito | Note |
|---|---|---|---|---|
| Logout ThothII | usare il comando dell’app | cookie ThothII revocato | | |
| SSO ancora attivo | riaprire ThothII | possibile nuovo accesso senza password; documentare | | |
| Logout Authentik globale | se configurato e in scope | comportamento conforme alla policy locale | | |
| Riavvio core | Sol riavvia in finestra controllata | sessione browser valida secondo TTL/policy | | |
| Provider indisponibile | prova controllata | nuovo login fallisce chiuso e redatto | | |
| Ripristino provider | ripetere diagnosi/login | servizio torna operativo | | |
Non dichiarare “logout globale” se è stato testato soltanto il logout locale di ThothII.
## 5. Sessioni PostgreSQL e isolamento
| Prova | Risultato atteso | Esito | Note |
|---|---|---|---|
| Migrazioni | `pending=[]`, `drifted=[]` | | |
| Schema | `thoth_sessions` nel database Supabase esistente | | |
| PostgREST | schema non esposto | | |
| RLS | forzata sulle tabelle previste | | |
| Utente A/B | ciascuno vede soltanto le proprie sessioni | | |
| Accesso incrociato | risposta not-found/negata come da contratto | | |
| Admin | accesso trasversale solo secondo permessi documentati | | |
| Credenziale migratore | non montata nel core | | |
| Schema clinico | nessun nuovo privilegio runtime | | |
## 6. Sessione completa sotto OIDC
Come utente ordinario, eseguire una domanda innocua approvata e completare F1–F8.
| Prova | Risultato atteso | Esito | Note |
|---|---|---|---|
| Creazione | sessione associata all’identità OIDC | | |
| Gate F1–F8 | tutti presentati e registrati correttamente | | |
| Resume | ritorna alla sessione corretta | | |
| SQL finale | sola lettura e validato | | |
| Persistenza | manifest, artefatti e decisioni in PostgreSQL | | |
| SSE/chat | funzionano live; non richiesti come artefatti persistiti | | |
| Riavvio | sessione di lavoro ancora disponibile | | |
## 7. Integrazione e pulizia finale
| Prova | Risultato atteso | Esito | Note |
|---|---|---|---|
| Endpoint temporaneo A | rimosso/non instradato | | |
| Vecchio stack | fermo, non esposto | | |
| Link sidebar | punta solo alla nuova release | | |
| Servizi privati | core/Qdrant/Ollama non pubblicati | | |
| Altri servizi Nginx | invariati e sani | | |
| Rollback | procedura verificata e disponibile | | |
| Evidenze | nessun secret o dato clinico identificabile | | |
## 8. Decisione
Decisione finale: `PROJECT_B_PASS` / `PROJECT_B_FAIL` / `PROJECT_B_PENDING`
Revisore e data: ______________________________________
Motivazione sintetica: ______________________________________
Conferma percorso finale “Aritmolab → sidebar → ThothII → SSO”: ______________________________