refactor: remove portal deployment coupling
This commit is contained in:
@@ -54,6 +54,8 @@ Il frontend renderizza questi widget-descriptor (registro in `src/widgets/`); il
|
||||
|
||||
## Come si lancia lo stack
|
||||
|
||||
Lo **stack completo** (Pi reale + DWH reale, serve VPN + `harness/.env` + `pi` sul PATH) si avvia con `./scripts/run-stack.sh` (frontend `:5173` → backend `:8787`).
|
||||
Lo stack locale si avvia con `./scripts/run-stack.sh`, dopo aver creato
|
||||
`deploy/env/local.env` da `deploy/env/local.env.example`. Il core Compose include Pi; DWH,
|
||||
vector DB, embedding e LLM sono endpoint esterni configurati nel file locale.
|
||||
|
||||
Comandi per singolo layer, test, lint: vedi il file `CLAUDE.md` nella radice del repo (guida operativa per Claude Code, tenuta sincronizzata con questa pagina).
|
||||
|
||||
@@ -45,13 +45,13 @@ services:
|
||||
- source: session_ca
|
||||
target: session_ca.pem
|
||||
networks:
|
||||
- portal
|
||||
- upstream
|
||||
restart: unless-stopped
|
||||
|
||||
networks:
|
||||
portal:
|
||||
upstream:
|
||||
external: true
|
||||
name: ${THT_PORTAL_NETWORK:-omics_portal_omics_network}
|
||||
name: ${THT_UPSTREAM_NETWORK:-thothii-upstream}
|
||||
|
||||
secrets:
|
||||
session_runtime_password:
|
||||
|
||||
@@ -14,27 +14,28 @@ Servono Docker Engine/Compose v2 su Linux oppure Docker Desktop su macOS/Windows
|
||||
```sh
|
||||
git clone <URL-REPOSITORY> ThothII
|
||||
cd ThothII
|
||||
cp .env.example .env
|
||||
mkdir -p deploy/secrets deploy/workspaces
|
||||
cp deploy/secrets/thothii.secrets.example deploy/secrets/thothii.secrets
|
||||
chmod 600 deploy/secrets/thothii.secrets
|
||||
cp deploy/env/local.env.example deploy/env/local.env
|
||||
```
|
||||
|
||||
Modificare **solo** questi file interni al clone:
|
||||
|
||||
| File | Cosa contiene |
|
||||
|---|---|
|
||||
| `.env` | endpoint, database, provider, `COMPOSE_FILE` e `COMPOSE_PROFILES`; mai password/token |
|
||||
| `deploy/secrets/thothii.secrets` | un bundle `NOME=VALORE`, mode host `0600` o `0400` |
|
||||
| `deploy/env/local.env` | endpoint, database e path Pi locali; mai password/token |
|
||||
| file protetti locali | credenziali e certificati, indicati dai binding del workspace |
|
||||
| `deploy/workspaces/<nome>.yaml` | adapter, endpoint non riservati, `roots` ed Evidence |
|
||||
|
||||
Il file `.env` viene caricato automaticamente da Docker Compose perché è nella radice del progetto. Il valore predefinito è `COMPOSE_FILE=compose.yaml`, con profili vuoti e `THT_SECRETS_FILE=deploy/secrets/thothii.secrets`. Perciò, dopo aver compilato `.env`, il bundle e almeno il workspace, l'avvio normale è sempre:
|
||||
Compilare `deploy/env/local.env`, incluso `PI_AUTH_FILE`, con gli endpoint esterni. L'avvio
|
||||
normale usa esplicitamente il file base e l'overlay locale:
|
||||
|
||||
```sh
|
||||
docker compose up --build -d
|
||||
docker compose --env-file deploy/env/local.env \
|
||||
-f compose.yaml -f deploy/compose.local.yaml up --build -d
|
||||
```
|
||||
|
||||
Non occorre usare `--env-file`, `-f` o `--profile` per questa installazione. Verificare lo stato con `docker compose ps` e aprire <http://127.0.0.1:8080>. `docker compose down` conserva il volume `thoth_data`; usare `down --volumes` solo per un ambiente effimero.
|
||||
Verificare lo stato con lo stesso comando Compose e aprire <http://127.0.0.1:8080>. Il core
|
||||
include Pi; il binario Pi non deve essere installato sull'host. `docker compose down` conserva i
|
||||
volumi; usare `down --volumes` solo per un ambiente effimero.
|
||||
|
||||
### Formato del bundle unico
|
||||
|
||||
@@ -55,21 +56,13 @@ Inserire solo le chiavi necessarie al profilo scelto. Il bundle viene montato in
|
||||
|
||||
Una catena CA PEM **non può essere inserita nel bundle**: contiene whitespace e viene rifiutata dal parser. Se un endpoint usa una CA privata, conservarla nel secret manager/host e aggiungere un override Compose revisionato che monti il file in `/run/secrets/ca-chain.pem` e imposti `THT_SSL_CA` (o il parametro dell'adapter). Il clone base non crea quel mount: questa è una limitazione intenzionale da considerare in fase di deployment.
|
||||
|
||||
### Overlay opzionali tramite `.env`
|
||||
### Overlay opzionali espliciti
|
||||
|
||||
Gli overlay non cambiano il comando operativo. Impostare in `.env`:
|
||||
|
||||
```dotenv
|
||||
# DWH/vector/embedding remoti (server applicativo o server con i DB):
|
||||
COMPOSE_FILE=compose.yaml:deploy/compose.production.yaml
|
||||
COMPOSE_PROFILES=
|
||||
|
||||
# pgvector locale (Mac, Windows o server autonomo):
|
||||
COMPOSE_FILE=compose.yaml:deploy/compose.local-vector.yaml
|
||||
COMPOSE_PROFILES=local-vector
|
||||
```
|
||||
|
||||
Su Windows usare `;` come separatore di `COMPOSE_FILE`. Per il preprocessing locale aggiungere `deploy/compose.preprocess.yaml:deploy/compose.preprocess-local-vector.yaml` e impostare `COMPOSE_PROFILES=local-vector,preprocess`; poi usare `docker compose run --rm preprocess-evidence` oppure `docker compose run --rm preprocess-dwh`.
|
||||
DWH/vector/embedding remoti restano endpoint del file locale o server. Per il solo preset di
|
||||
sviluppo pgvector, aggiungere `-f deploy/compose.local-vector.yaml --profile local-vector` al
|
||||
comando base. Per il preprocessing aggiungere anche
|
||||
`-f deploy/compose.preprocess.yaml -f deploy/compose.preprocess-local-vector.yaml --profile preprocess`,
|
||||
poi usare `docker compose run --rm preprocess-evidence` oppure `preprocess-dwh` con gli stessi argomenti.
|
||||
|
||||
## Workspace, adapter e Evidence
|
||||
|
||||
@@ -116,11 +109,10 @@ il bind mount/runtime adapter corrispondente. Non inserire la password nel works
|
||||
|
||||
## 1. Server remoto insieme ai database e al vector DB
|
||||
|
||||
Usare quando il server Docker è nella stessa rete del DWH e del vector DB (containerizzati o meno). Il file `.env` può restare sul default, senza profili, impostando gli endpoint raggiungibili localmente:
|
||||
Usare quando il server Docker è nella stessa rete del DWH e del vector DB (containerizzati o meno).
|
||||
Compilare `deploy/env/local.env` con gli endpoint raggiungibili localmente:
|
||||
|
||||
```dotenv
|
||||
COMPOSE_FILE=compose.yaml
|
||||
COMPOSE_PROFILES=
|
||||
THT_DB_NAME=warehouse
|
||||
THT_DWH_REST_URL=https://dwh.internal.example
|
||||
THT_VEC_REST_URL=https://vectors.internal.example
|
||||
@@ -143,17 +135,15 @@ claim normalizzati `X-Thoth-Principal-Issuer`, `X-Thoth-Principal-Subject`,
|
||||
`X-Thoth-Principal-Display-Name` e `X-Thoth-Is-Admin` attesi dal core. Non esporre direttamente
|
||||
la porta pubblicata da nginx.
|
||||
|
||||
Se il server deve essere raggiungibile da altri host, sostituire `COMPOSE_FILE` con
|
||||
`compose.yaml:deploy/compose.production.yaml`, configurare il proxy autenticato e impostare
|
||||
Se il server deve essere raggiungibile da altri host, usare il profilo
|
||||
`deploy/compose.server.yaml`, configurare il proxy autenticato e impostare
|
||||
`AUTH_MODE=upstream`/`THOTH_PUBLIC_EXPOSURE=true` come descritto nella sezione di trust boundary.
|
||||
|
||||
## 2. Mac locale
|
||||
|
||||
Installare Docker Desktop e, se usato, Ollama sul Mac. Nel `.env` selezionare il profilo locale:
|
||||
Installare Docker Desktop e, se usato, Ollama sul Mac. In `deploy/env/local.env` impostare gli endpoint:
|
||||
|
||||
```dotenv
|
||||
COMPOSE_FILE=compose.yaml:deploy/compose.local-vector.yaml
|
||||
COMPOSE_PROFILES=local-vector
|
||||
THT_DB_NAME=warehouse
|
||||
THT_DWH_REST_URL=https://dwh.example.test
|
||||
THT_OLLAMA_URL=http://host.docker.internal:11434
|
||||
@@ -173,11 +163,9 @@ Poi eseguire il comando standard `docker compose up --build -d`. Il primo avvio
|
||||
|
||||
## 3. PC Windows locale
|
||||
|
||||
Usare Docker Desktop con backend WSL2 e abilitare la condivisione della directory del clone. Modificare `.env` con il separatore Windows:
|
||||
Usare Docker Desktop con backend WSL2 e abilitare la condivisione della directory del clone. Modificare `deploy/env/local.env`:
|
||||
|
||||
```dotenv
|
||||
COMPOSE_FILE=compose.yaml;deploy/compose.local-vector.yaml
|
||||
COMPOSE_PROFILES=local-vector
|
||||
THT_DB_NAME=warehouse
|
||||
THT_DWH_REST_URL=https://dwh.example.test
|
||||
THT_OLLAMA_URL=http://host.docker.internal:11434
|
||||
@@ -195,11 +183,11 @@ Se un bind mount viene rifiutato, aggiungere la cartella del repository a Docker
|
||||
|
||||
## 4. Server applicativo distinto da DB ed Evidence
|
||||
|
||||
Usare il profilo production e consentire dal firewall solo le destinazioni necessarie:
|
||||
Usare il profilo server e consentire dal firewall solo le destinazioni necessarie:
|
||||
|
||||
```dotenv
|
||||
COMPOSE_FILE=compose.yaml:deploy/compose.production.yaml
|
||||
COMPOSE_PROFILES=
|
||||
# Avvio: docker compose --env-file deploy/env/server.env \
|
||||
# -f compose.yaml -f deploy/compose.server.yaml up --build -d
|
||||
THT_DB_NAME=warehouse
|
||||
THT_DWH_REST_URL=https://dwh.example.test
|
||||
THT_VEC_REST_URL=https://vectors.example.test
|
||||
|
||||
Reference in New Issue
Block a user