fix: close deployment decoupling review
This commit is contained in:
+2
-2
@@ -8,8 +8,8 @@ La documentazione è divisa in due aree:
|
||||
|
||||
Come funziona il sistema: architettura, specifiche di design delle singole funzionalità, piani di implementazione, report di test. Parte da qui: [Panoramica dell'architettura](architecture/overview.md).
|
||||
|
||||
Per installare l'applicazione in Docker nei quattro contesti operativi, partendo dal comando
|
||||
predefinito `docker compose up --build -d` e dal bundle unico dei secret:
|
||||
Per installare l'applicazione in Docker nei quattro contesti operativi, usando il file env,
|
||||
`compose.yaml`, l'overlay locale/server e il bundle di secret montato:
|
||||
[Installazione Docker nei quattro contesti](installazione-docker-4-contesti.md).
|
||||
|
||||
## Considerazioni Generali
|
||||
|
||||
@@ -1,13 +0,0 @@
|
||||
# Optional override for an HTTPS Git remote. Both source paths are required absolute paths to
|
||||
# existing operator-managed files; neither file content belongs in the base Compose example.
|
||||
services:
|
||||
core:
|
||||
environment:
|
||||
GIT_CONFIG_COUNT: "2"
|
||||
GIT_CONFIG_KEY_0: credential.helper
|
||||
GIT_CONFIG_VALUE_0: store --file=/run/secrets/workspace-registry-git-credentials
|
||||
GIT_CONFIG_KEY_1: http.sslCAInfo
|
||||
GIT_CONFIG_VALUE_1: /run/secrets/workspace-registry-git-ca
|
||||
volumes:
|
||||
- ${THT_WORKSPACE_GIT_CREDENTIALS_FILE:?set THT_WORKSPACE_GIT_CREDENTIALS_FILE}:/run/secrets/workspace-registry-git-credentials:ro
|
||||
- ${THT_WORKSPACE_GIT_CA_FILE:?set THT_WORKSPACE_GIT_CA_FILE}:/run/secrets/workspace-registry-git-ca:ro
|
||||
@@ -1,9 +0,0 @@
|
||||
# Optional override for an SSH Git remote. Source paths are required absolute operator-managed
|
||||
# files. Host-key checking remains strict; do not add a fallback known-hosts or key mount.
|
||||
services:
|
||||
core:
|
||||
environment:
|
||||
GIT_SSH_COMMAND: ssh -i /run/secrets/workspace-registry-git-ssh-key -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=/run/secrets/workspace-registry-git-known-hosts
|
||||
volumes:
|
||||
- ${THT_WORKSPACE_GIT_SSH_KEY_FILE:?set THT_WORKSPACE_GIT_SSH_KEY_FILE}:/run/secrets/workspace-registry-git-ssh-key:ro
|
||||
- ${THT_WORKSPACE_GIT_KNOWN_HOSTS_FILE:?set THT_WORKSPACE_GIT_KNOWN_HOSTS_FILE}:/run/secrets/workspace-registry-git-known-hosts:ro
|
||||
@@ -1,39 +0,0 @@
|
||||
# Standalone local registry example. Copy to an untracked operator directory and set the absolute
|
||||
# THT_SOURCE_ROOT in .env. Add only the selected Git transport override from this directory.
|
||||
name: thothii-workspace-registry-local
|
||||
|
||||
services:
|
||||
core:
|
||||
image: thothii-core:local
|
||||
build:
|
||||
context: ${THT_SOURCE_ROOT:?set THT_SOURCE_ROOT to the absolute ThothII source checkout}
|
||||
dockerfile: docker/core.Dockerfile
|
||||
env_file:
|
||||
- path: ${THT_WORKSPACE_BINDINGS_ENV_FILE:?set THT_WORKSPACE_BINDINGS_ENV_FILE to an absolute THT_WS bindings file}
|
||||
required: true
|
||||
environment:
|
||||
HOST: 0.0.0.0
|
||||
PORT: "8787"
|
||||
AUTH_MODE: none
|
||||
THT_SESSION_STORAGE: local
|
||||
THT_HOME: /data/local-home
|
||||
SETTINGS_FILE: /data/settings/settings.json
|
||||
THT_HARNESS_DIR: /app/harness
|
||||
THT_BIN: /opt/venv/bin/tht
|
||||
THT_WORKSPACE_REGISTRY_ROOT: /data/workspace-registry
|
||||
THT_WORKSPACE_GIT_REMOTE: ${THT_WORKSPACE_GIT_REMOTE:-ssh://git@git.example.invalid/platform/thoth-workspaces.git}
|
||||
THT_WORKSPACE_GIT_BRANCH: ${THT_WORKSPACE_GIT_BRANCH:-main}
|
||||
THT_WORKSPACE_INSTALLATION_ID: ${THT_WORKSPACE_INSTALLATION_ID:-local-laptop}
|
||||
THT_WORKSPACE_GIT_AUTHOR_NAME: ${THT_WORKSPACE_GIT_AUTHOR_NAME:-Thoth Workspace Registry}
|
||||
THT_WORKSPACE_GIT_AUTHOR_EMAIL: ${THT_WORKSPACE_GIT_AUTHOR_EMAIL:-thoth-workspace-registry@localhost}
|
||||
THT_WORKSPACE_SECRET_ROOTS: /run/secrets
|
||||
ports:
|
||||
- "127.0.0.1:8787:8787"
|
||||
volumes:
|
||||
- thoth-local-data:/data
|
||||
- workspace-registry:/data/workspace-registry
|
||||
restart: "no"
|
||||
|
||||
volumes:
|
||||
thoth-local-data: {}
|
||||
workspace-registry: {}
|
||||
@@ -1,60 +0,0 @@
|
||||
# Server registry example. Copy to a reviewed, untracked operator directory and set absolute host
|
||||
# paths and Git values in .env. Add a selected Git transport override from this directory.
|
||||
name: thothii-workspace-registry-server
|
||||
|
||||
services:
|
||||
core:
|
||||
image: thothii-core:local
|
||||
build:
|
||||
context: ${THT_SOURCE_ROOT:?set THT_SOURCE_ROOT to the absolute ThothII source checkout}
|
||||
dockerfile: docker/core.Dockerfile
|
||||
env_file:
|
||||
- path: ${THT_WORKSPACE_BINDINGS_ENV_FILE:?set THT_WORKSPACE_BINDINGS_ENV_FILE to an absolute THT_WS bindings file}
|
||||
required: true
|
||||
environment:
|
||||
HOST: 0.0.0.0
|
||||
PORT: "8787"
|
||||
AUTH_MODE: upstream
|
||||
THOTH_PUBLIC_EXPOSURE: "true"
|
||||
THT_SESSION_STORAGE: postgres
|
||||
THT_CONFIG: /app/harness/workspaces/server-sessions.yaml
|
||||
THT_SESSION_DB_HOST: ${THT_SESSION_DB_HOST:?set THT_SESSION_DB_HOST}
|
||||
THT_SESSION_DB_PORT: ${THT_SESSION_DB_PORT:-5432}
|
||||
THT_SESSION_DB_NAME: ${THT_SESSION_DB_NAME:?set THT_SESSION_DB_NAME}
|
||||
THT_SESSION_RUNTIME_USER: ${THT_SESSION_RUNTIME_USER:?set THT_SESSION_RUNTIME_USER}
|
||||
THT_SESSION_RUNTIME_PASSWORD_FILE: /run/secrets/session_runtime_password
|
||||
THT_SESSION_DB_SSLMODE: ${THT_SESSION_DB_SSLMODE:-verify-full}
|
||||
THT_SESSION_DB_SSLROOTCERT: /run/secrets/session_ca.pem
|
||||
THT_HARNESS_DIR: /app/harness
|
||||
THT_BIN: /opt/venv/bin/tht
|
||||
SETTINGS_FILE: /data/settings/settings.json
|
||||
THT_WORKSPACE_REGISTRY_ROOT: /data/workspace-registry
|
||||
THT_WORKSPACE_GIT_REMOTE: ${THT_WORKSPACE_GIT_REMOTE:-ssh://git@git.example.invalid/platform/thoth-workspaces.git}
|
||||
THT_WORKSPACE_GIT_BRANCH: ${THT_WORKSPACE_GIT_BRANCH:-main}
|
||||
THT_WORKSPACE_INSTALLATION_ID: ${THT_WORKSPACE_INSTALLATION_ID:-production-1}
|
||||
THT_WORKSPACE_GIT_AUTHOR_NAME: ${THT_WORKSPACE_GIT_AUTHOR_NAME:-Thoth Workspace Registry}
|
||||
THT_WORKSPACE_GIT_AUTHOR_EMAIL: ${THT_WORKSPACE_GIT_AUTHOR_EMAIL:-thoth-workspace-registry@localhost}
|
||||
THT_WORKSPACE_SECRET_ROOTS: /run/secrets
|
||||
volumes:
|
||||
- ${THT_HOST_DATA_ROOT:-/srv/thothii/data}:/data
|
||||
- ${THT_WORKSPACE_REGISTRY_HOST_PATH:-/srv/thothii/workspace-registry}:/data/workspace-registry
|
||||
- ${THT_SERVER_WORKSPACE_CONFIG:?set THT_SERVER_WORKSPACE_CONFIG}:/app/harness/workspaces/server-sessions.yaml:ro
|
||||
secrets:
|
||||
- source: session_runtime_password
|
||||
target: session_runtime_password
|
||||
- source: session_ca
|
||||
target: session_ca.pem
|
||||
networks:
|
||||
- upstream
|
||||
restart: unless-stopped
|
||||
|
||||
networks:
|
||||
upstream:
|
||||
external: true
|
||||
name: ${THT_UPSTREAM_NETWORK:-thothii-upstream}
|
||||
|
||||
secrets:
|
||||
session_runtime_password:
|
||||
file: ${THT_SESSION_RUNTIME_PASSWORD_SOURCE:?set THT_SESSION_RUNTIME_PASSWORD_SOURCE}
|
||||
session_ca:
|
||||
file: ${THT_SESSION_CA_SOURCE:?set THT_SESSION_CA_SOURCE}
|
||||
@@ -1,13 +1,13 @@
|
||||
# Copy to an untracked operator file. This file contains only non-secret THT_WS_* bindings.
|
||||
# Every *_FILE value is a container path supplied by the generated local connector override.
|
||||
THT_WS_PSD_CLINICAL_DWH_TRANSPORT=postgres_direct
|
||||
THT_WS_PSD_CLINICAL_DWH_HOST=dwh.internal.example
|
||||
THT_WS_PSD_CLINICAL_DWH_PORT=5432
|
||||
THT_WS_PSD_CLINICAL_DWH_USER=thoth_reader
|
||||
THT_WS_PSD_CLINICAL_DWH_PASSWORD_FILE=/run/secrets/psd-clinical-dwh-password
|
||||
THT_WS_PSD_CLINICAL_VECTOR_TRANSPORT=pgvector_direct
|
||||
THT_WS_PSD_CLINICAL_VECTOR_HOST=vector.internal.example
|
||||
THT_WS_PSD_CLINICAL_VECTOR_PORT=5432
|
||||
THT_WS_PSD_CLINICAL_VECTOR_USER=thoth_vector_reader
|
||||
THT_WS_PSD_CLINICAL_VECTOR_PASSWORD_FILE=/run/secrets/psd-clinical-vector-password
|
||||
THT_WS_PSD_CLINICAL_EMBEDDING_BASE_URL=https://embeddings.internal.example
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_TRANSPORT=postgres_direct
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_HOST=dwh.internal.example
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_PORT=5432
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_USER=thoth_reader
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_PASSWORD_FILE=/run/secrets/north-star-research-dwh-password
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_TRANSPORT=pgvector_direct
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_HOST=vector.internal.example
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_PORT=5432
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_USER=thoth_vector_reader
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_PASSWORD_FILE=/run/secrets/north-star-research-vector-password
|
||||
THT_WS_NORTH_STAR_RESEARCH_EMBEDDING_BASE_URL=https://embeddings.internal.example
|
||||
|
||||
@@ -34,14 +34,16 @@ workspaces/<workspace-id>.md
|
||||
For SSH, use a scoped deploy key, a verified `known_hosts` file, and strict host-key checking. For
|
||||
HTTPS, use Git Credential Manager or a secret-manager-created credentials file. Mount a private
|
||||
HTTPS CA as its own file. Do not disable host or certificate verification. The base Compose file
|
||||
does not mount a Git credential: add exactly one optional `git-ssh.workspace-registry.yaml` or
|
||||
`git-https.workspace-registry.yaml` override, so unused credential paths are never bind-mounted.
|
||||
does not mount a Git credential: add exactly one optional `deploy/compose.git-ssh.yaml` or
|
||||
`deploy/compose.git-https.yaml` override, so unused credential paths are never bind-mounted.
|
||||
|
||||
```dotenv
|
||||
THT_WORKSPACE_GIT_REMOTE=ssh://git@git.example.invalid/platform/thoth-workspaces.git
|
||||
THT_WORKSPACE_GIT_BRANCH=main
|
||||
THT_WORKSPACE_INSTALLATION_ID=local-laptop
|
||||
THT_SOURCE_ROOT=/absolute/path/to/ThothII
|
||||
PI_AUTH_FILE=/absolute/path/installation-secrets/pi-auth.json
|
||||
THT_SECRETS_FILE=/absolute/path/installation-secrets/thothii.secrets
|
||||
THT_WORKSPACE_GIT_SSH_KEY_FILE=/absolute/path/installation-secrets/git-ssh-key
|
||||
THT_WORKSPACE_GIT_KNOWN_HOSTS_FILE=/absolute/path/installation-secrets/git-known-hosts
|
||||
THT_WORKSPACE_GIT_CA_FILE=/absolute/path/installation-secrets/git-ca.pem
|
||||
@@ -69,12 +71,12 @@ state/ # active revision and registry state
|
||||
locks/ # short-lived publish locks
|
||||
```
|
||||
|
||||
Installation variables are deterministic: `psd-clinical` becomes `PSD_CLINICAL`, and every name
|
||||
Installation variables are deterministic: `north-star-research` becomes `NORTH_STAR_RESEARCH`, and every name
|
||||
is `THT_WS_<NAMESPACE>_<ROLE>_<SUFFIX>`. Copy
|
||||
[the bindings env example](examples/workspace-bindings.env.example) to an untracked operator file
|
||||
and set its absolute path as `THT_WORKSPACE_BINDINGS_ENV_FILE`. It is loaded only into `core`.
|
||||
Credentials and certificates use `*_FILE` path variables that must point inside `/run/secrets`.
|
||||
If declared, `THT_WS_PSD_CLINICAL_VECTOR_WRITER_API_KEY_FILE` is distinct from the vector reader
|
||||
If declared, `THT_WS_NORTH_STAR_RESEARCH_VECTOR_WRITER_API_KEY_FILE` is distinct from the vector reader
|
||||
file; a reader credential is never repurposed for writing.
|
||||
|
||||
## Direct PostgreSQL, REST, and SSH tunnel bindings
|
||||
@@ -87,41 +89,41 @@ copy or maintain a workspace-specific Compose override.
|
||||
|
||||
```dotenv
|
||||
# Direct PostgreSQL and pgvector
|
||||
THT_WS_PSD_CLINICAL_DWH_TRANSPORT=postgres_direct
|
||||
THT_WS_PSD_CLINICAL_DWH_HOST=dwh.example.invalid
|
||||
THT_WS_PSD_CLINICAL_DWH_PORT=5432
|
||||
THT_WS_PSD_CLINICAL_DWH_USER=thoth_reader
|
||||
THT_WS_PSD_CLINICAL_DWH_PASSWORD_FILE=/run/secrets/psd-dwh-reader
|
||||
THT_WS_PSD_CLINICAL_VECTOR_TRANSPORT=pgvector_direct
|
||||
THT_WS_PSD_CLINICAL_VECTOR_HOST=vector.example.invalid
|
||||
THT_WS_PSD_CLINICAL_VECTOR_PORT=5432
|
||||
THT_WS_PSD_CLINICAL_VECTOR_USER=thoth_vector_reader
|
||||
THT_WS_PSD_CLINICAL_VECTOR_PASSWORD_FILE=/run/secrets/psd-vector-reader
|
||||
THT_WS_PSD_CLINICAL_EMBEDDING_BASE_URL=https://embeddings.example.invalid
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_TRANSPORT=postgres_direct
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_HOST=dwh.example.invalid
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_PORT=5432
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_USER=thoth_reader
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_PASSWORD_FILE=/run/secrets/north-star-research-dwh-password
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_TRANSPORT=pgvector_direct
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_HOST=vector.example.invalid
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_PORT=5432
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_USER=thoth_vector_reader
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_PASSWORD_FILE=/run/secrets/north-star-research-vector-password
|
||||
THT_WS_NORTH_STAR_RESEARCH_EMBEDDING_BASE_URL=https://embeddings.example.invalid
|
||||
```
|
||||
|
||||
```dotenv
|
||||
# REST; an API-key file is needed only for a declared bearer/x-api-key diagnostic.
|
||||
THT_WS_PSD_CLINICAL_DWH_TRANSPORT=rest_api
|
||||
THT_WS_PSD_CLINICAL_DWH_BASE_URL=https://dwh.example.invalid
|
||||
THT_WS_PSD_CLINICAL_DWH_API_KEY_FILE=/run/secrets/psd-dwh-api-key
|
||||
THT_WS_PSD_CLINICAL_VECTOR_TRANSPORT=rest_api
|
||||
THT_WS_PSD_CLINICAL_VECTOR_BASE_URL=https://vectors.example.invalid
|
||||
THT_WS_PSD_CLINICAL_VECTOR_API_KEY_FILE=/run/secrets/psd-vector-api-key
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_TRANSPORT=rest_api
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_BASE_URL=https://dwh.example.invalid
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_API_KEY_FILE=/run/secrets/north-star-research-dwh-api-key
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_TRANSPORT=rest_api
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_BASE_URL=https://vectors.example.invalid
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_API_KEY_FILE=/run/secrets/north-star-research-vector-api-key
|
||||
```
|
||||
|
||||
```dotenv
|
||||
# SSH tunnel diagnostic only; runtime sessions are fail-closed in this release.
|
||||
THT_WS_PSD_CLINICAL_DWH_TRANSPORT=ssh_tunnel
|
||||
THT_WS_PSD_CLINICAL_DWH_USER=thoth_reader
|
||||
THT_WS_PSD_CLINICAL_DWH_PASSWORD_FILE=/run/secrets/psd-dwh-reader
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_HOST=bastion.example.invalid
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_PORT=22
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_USER=thoth_tunnel
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_PRIVATE_KEY_FILE=/run/secrets/psd-dwh-tunnel-key
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_KNOWN_HOSTS_FILE=/run/secrets/psd-dwh-known-hosts
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_TARGET_HOST=dwh.internal.example
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_TARGET_PORT=5432
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_TRANSPORT=ssh_tunnel
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_USER=thoth_reader
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_PASSWORD_FILE=/run/secrets/north-star-research-dwh-password
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_HOST=bastion.example.invalid
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_PORT=22
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_USER=thoth_tunnel
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_PRIVATE_KEY_FILE=/run/secrets/north-star-research-dwh-tunnel-key
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_KNOWN_HOSTS_FILE=/run/secrets/north-star-research-dwh-known-hosts
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_TARGET_HOST=dwh.internal.example
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_TARGET_PORT=5432
|
||||
```
|
||||
|
||||
Repeat the SSH names for `VECTOR` where needed. REST diagnostics reject a private per-request CA
|
||||
@@ -134,31 +136,36 @@ before creating sessions. Git pull/push over SSH remains fully supported and is
|
||||
|
||||
## Bootstrap, first pull, and diagnostics
|
||||
|
||||
Copy [the local Compose example](examples/local-compose.workspace-registry.yaml), exactly one
|
||||
selected [SSH Git override](examples/git-ssh.workspace-registry.yaml) or [HTTPS Git override](examples/git-https.workspace-registry.yaml),
|
||||
and [the bindings env example](examples/workspace-bindings.env.example) into an untracked operator
|
||||
directory. Keep `THT_SOURCE_ROOT` and the absolute `THT_WORKSPACE_BINDINGS_ENV_FILE` in its `.env`
|
||||
for Compose interpolation; this keeps the copied Compose file buildable and confines `THT_WS_*`
|
||||
values to `core`. A Compose `.env` file is not a shell environment, so do not import it into the
|
||||
maintenance shell. Instead, explicitly export the two non-secret paths before running the commands.
|
||||
Create the host secret files named by the selected Git transport and every declared connector
|
||||
`*_SOURCE`, then generate the connector override and render through the preflight wrapper. The
|
||||
wrapper is required: it rejects unsafe source paths and a combined SSH+HTTPS Git selection before
|
||||
Compose runs.
|
||||
Use the repository's canonical `compose.yaml` plus `deploy/compose.local.yaml`; they always start
|
||||
the mandatory `frontend` and `core` services. Do not copy or maintain a standalone application
|
||||
Compose file. Copy [the bindings env example](examples/workspace-bindings.env.example) into an
|
||||
untracked operator directory and create a protected operator env file from
|
||||
`deploy/env/local.env.example`. It must contain absolute `PI_AUTH_FILE`,
|
||||
`THT_SECRETS_FILE`, `THT_WORKSPACE_BINDINGS_ENV_FILE`, and connector `*_SOURCE` paths.
|
||||
The Pi auth JSON, runtime secret bundle, and each connector credential remain separate protected
|
||||
host files and are mounted read-only; their contents never enter the operator env or rendered
|
||||
Compose.
|
||||
|
||||
Select exactly one repository Git transport override, `deploy/compose.git-ssh.yaml` or
|
||||
`deploy/compose.git-https.yaml`. A Compose env file is not a shell environment, so export only the
|
||||
non-secret paths required by the maintenance commands. Generate the connector override and render
|
||||
through the preflight wrapper, which rejects unsafe paths and combined SSH+HTTPS selection.
|
||||
|
||||
```sh
|
||||
export THT_SOURCE_ROOT=/absolute/path/to/ThothII
|
||||
export THT_WORKSPACE_BINDINGS_ENV_FILE="$(pwd -P)/workspace-bindings.env"
|
||||
"$THT_SOURCE_ROOT/scripts/generate-connector-secrets-override.sh" --bindings-env "$THT_WORKSPACE_BINDINGS_ENV_FILE" --operator-env .env --output connector-secrets.local.yaml
|
||||
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file .env \
|
||||
-f compose.workspace-registry.yaml -f git-ssh.workspace-registry.yaml -f connector-secrets.local.yaml config --quiet
|
||||
export THT_OPERATOR_ENV=/absolute/path/to/operator/local.env
|
||||
export THT_WORKSPACE_BINDINGS_ENV_FILE=/absolute/path/to/operator/workspace-bindings.env
|
||||
export THT_CONNECTOR_OVERRIDE=/absolute/path/to/operator/connector-secrets.local.yaml
|
||||
"$THT_SOURCE_ROOT/scripts/generate-connector-secrets-override.sh" --bindings-env "$THT_WORKSPACE_BINDINGS_ENV_FILE" --operator-env "$THT_OPERATOR_ENV" --output "$THT_CONNECTOR_OVERRIDE"
|
||||
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file "$THT_OPERATOR_ENV" \
|
||||
-f "$THT_SOURCE_ROOT/compose.yaml" -f "$THT_SOURCE_ROOT/deploy/compose.local.yaml" \
|
||||
-f "$THT_SOURCE_ROOT/deploy/compose.git-ssh.yaml" -f "$THT_CONNECTOR_OVERRIDE" config --quiet
|
||||
```
|
||||
|
||||
From the operator directory:
|
||||
|
||||
```sh
|
||||
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file .env \
|
||||
-f compose.workspace-registry.yaml -f git-ssh.workspace-registry.yaml -f connector-secrets.local.yaml up --build -d
|
||||
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file "$THT_OPERATOR_ENV" \
|
||||
-f "$THT_SOURCE_ROOT/compose.yaml" -f "$THT_SOURCE_ROOT/deploy/compose.local.yaml" \
|
||||
-f "$THT_SOURCE_ROOT/deploy/compose.git-ssh.yaml" -f "$THT_CONNECTOR_OVERRIDE" up --build -d
|
||||
curl --fail --silent http://127.0.0.1:8787/health
|
||||
curl --fail --silent http://127.0.0.1:8787/workspace-registry/status
|
||||
curl --fail --silent http://127.0.0.1:8787/workspaces
|
||||
@@ -169,7 +176,7 @@ Use `POST /workspace-registry/pull` to fetch later revisions. Run workspace diag
|
||||
required bindings are mounted. The optional writer probe uses a distinct writer file and removes
|
||||
its uniquely named temporary record; ordinary diagnostics are read-only.
|
||||
|
||||
To migrate an existing PSD descriptor, create/clone an empty private remote, set the absolute
|
||||
To migrate an existing legacy descriptor, create/clone an empty private remote, set the absolute
|
||||
`THT_SOURCE_ROOT`, transform with absolute paths, review the schema-v1 result, explicitly add
|
||||
vector database/schema and the complete schema-v2 contract, then commit/push. The transformer
|
||||
never imports `${ENV}` values or secrets.
|
||||
@@ -177,7 +184,7 @@ never imports `${ENV}` values or secrets.
|
||||
```sh
|
||||
THT_SOURCE_ROOT=/absolute/path/to/ThothII
|
||||
npm --prefix "$THT_SOURCE_ROOT/backend" run build
|
||||
node "$THT_SOURCE_ROOT/backend/dist/workspaces/migrate-legacy.js" --input /absolute/path/psd.yaml --output /absolute/path/thoth-workspaces
|
||||
node "$THT_SOURCE_ROOT/backend/dist/workspaces/migrate-legacy.js" --input /absolute/path/legacy.yaml --output /absolute/path/thoth-workspaces
|
||||
```
|
||||
|
||||
## Publish, update, backup, outage recovery, and rollback
|
||||
|
||||
@@ -48,11 +48,13 @@ THT_WORKSPACE_GIT_CREDENTIALS_FILE=/srv/thothii/secrets/git-credentials
|
||||
THT_WORKSPACE_GIT_CA_FILE=/srv/thothii/secrets/git-ca.pem
|
||||
THT_WORKSPACE_GIT_SSH_KEY_FILE=/srv/thothii/secrets/git-ssh-key
|
||||
THT_WORKSPACE_GIT_KNOWN_HOSTS_FILE=/srv/thothii/secrets/git-known-hosts
|
||||
PI_AUTH_FILE=/srv/thothii/secrets/pi-auth.json
|
||||
THT_SECRETS_FILE=/srv/thothii/secrets/thothii.secrets
|
||||
```
|
||||
|
||||
Use the credential file for HTTPS, or key and known-hosts for SSH. The base server Compose file
|
||||
mounts neither transport; add exactly one [HTTPS override](examples/git-https.workspace-registry.yaml)
|
||||
or [SSH override](examples/git-ssh.workspace-registry.yaml). Strict host-key checking stays enabled
|
||||
mounts neither transport; add exactly one `deploy/compose.git-https.yaml`
|
||||
or `deploy/compose.git-ssh.yaml` override. Strict host-key checking stays enabled
|
||||
and Git stderr is not exposed by the API. Rotate by atomically replacing the secret file,
|
||||
restarting `core`, and performing pull/status; never put the material in an environment variable or
|
||||
rendered Compose output.
|
||||
@@ -75,9 +77,9 @@ The runtime registry layout is persistent and must be backed up together:
|
||||
/data/workspace-registry/locks/
|
||||
```
|
||||
|
||||
Variable names derive from the immutable ID: `psd-clinical` becomes `PSD_CLINICAL`, producing
|
||||
`THT_WS_PSD_CLINICAL_DWH_PASSWORD_FILE`. A declared vector writer uses the distinct
|
||||
`THT_WS_PSD_CLINICAL_VECTOR_WRITER_API_KEY_FILE`; a reader file is never a writer substitute.
|
||||
Variable names derive from the immutable ID: `north-star-research` becomes `NORTH_STAR_RESEARCH`, producing
|
||||
`THT_WS_NORTH_STAR_RESEARCH_DWH_PASSWORD_FILE`. A declared vector writer uses the distinct
|
||||
`THT_WS_NORTH_STAR_RESEARCH_VECTOR_WRITER_API_KEY_FILE`; a reader file is never a writer substitute.
|
||||
Copy [the bindings env example](examples/workspace-bindings.env.example) to the protected operator
|
||||
directory. Every path-valued `*_FILE` entry needs an absolute host-only `*_SOURCE` path. Generate
|
||||
the untracked connector override from those files during bootstrap; do not copy or maintain a
|
||||
@@ -90,41 +92,41 @@ dimensions, and distance as Git-shared identity.
|
||||
|
||||
```dotenv
|
||||
# Direct PostgreSQL/pgvector with verified native TLS if a CA path is supplied.
|
||||
THT_WS_PSD_CLINICAL_DWH_TRANSPORT=postgres_direct
|
||||
THT_WS_PSD_CLINICAL_DWH_HOST=dwh.internal.example
|
||||
THT_WS_PSD_CLINICAL_DWH_PORT=5432
|
||||
THT_WS_PSD_CLINICAL_DWH_USER=thoth_reader
|
||||
THT_WS_PSD_CLINICAL_DWH_PASSWORD_FILE=/run/secrets/psd-dwh-reader
|
||||
THT_WS_PSD_CLINICAL_VECTOR_TRANSPORT=pgvector_direct
|
||||
THT_WS_PSD_CLINICAL_VECTOR_HOST=vector.internal.example
|
||||
THT_WS_PSD_CLINICAL_VECTOR_PORT=5432
|
||||
THT_WS_PSD_CLINICAL_VECTOR_USER=thoth_vector_reader
|
||||
THT_WS_PSD_CLINICAL_VECTOR_PASSWORD_FILE=/run/secrets/psd-vector-reader
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_TRANSPORT=postgres_direct
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_HOST=dwh.internal.example
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_PORT=5432
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_USER=thoth_reader
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_PASSWORD_FILE=/run/secrets/north-star-research-dwh-password
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_TRANSPORT=pgvector_direct
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_HOST=vector.internal.example
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_PORT=5432
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_USER=thoth_vector_reader
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_PASSWORD_FILE=/run/secrets/north-star-research-vector-password
|
||||
```
|
||||
|
||||
```dotenv
|
||||
# REST needs API-key file paths only when the descriptor declares authenticated diagnostics.
|
||||
THT_WS_PSD_CLINICAL_DWH_TRANSPORT=rest_api
|
||||
THT_WS_PSD_CLINICAL_DWH_BASE_URL=https://dwh.internal.example
|
||||
THT_WS_PSD_CLINICAL_DWH_API_KEY_FILE=/run/secrets/psd-dwh-api-key
|
||||
THT_WS_PSD_CLINICAL_VECTOR_TRANSPORT=rest_api
|
||||
THT_WS_PSD_CLINICAL_VECTOR_BASE_URL=https://vectors.internal.example
|
||||
THT_WS_PSD_CLINICAL_VECTOR_API_KEY_FILE=/run/secrets/psd-vector-api-key
|
||||
THT_WS_PSD_CLINICAL_EMBEDDING_BASE_URL=https://embeddings.internal.example
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_TRANSPORT=rest_api
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_BASE_URL=https://dwh.internal.example
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_API_KEY_FILE=/run/secrets/north-star-research-dwh-api-key
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_TRANSPORT=rest_api
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_BASE_URL=https://vectors.internal.example
|
||||
THT_WS_NORTH_STAR_RESEARCH_VECTOR_API_KEY_FILE=/run/secrets/north-star-research-vector-api-key
|
||||
THT_WS_NORTH_STAR_RESEARCH_EMBEDDING_BASE_URL=https://embeddings.internal.example
|
||||
```
|
||||
|
||||
```dotenv
|
||||
# SSH tunnel diagnostic only; runtime sessions are fail-closed in this release.
|
||||
THT_WS_PSD_CLINICAL_DWH_TRANSPORT=ssh_tunnel
|
||||
THT_WS_PSD_CLINICAL_DWH_USER=thoth_reader
|
||||
THT_WS_PSD_CLINICAL_DWH_PASSWORD_FILE=/run/secrets/psd-dwh-reader
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_HOST=bastion.internal.example
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_PORT=22
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_USER=thoth_tunnel
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_PRIVATE_KEY_FILE=/run/secrets/psd-dwh-tunnel-key
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_KNOWN_HOSTS_FILE=/run/secrets/psd-dwh-known-hosts
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_TARGET_HOST=dwh.internal.example
|
||||
THT_WS_PSD_CLINICAL_DWH_SSH_TARGET_PORT=5432
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_TRANSPORT=ssh_tunnel
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_USER=thoth_reader
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_PASSWORD_FILE=/run/secrets/north-star-research-dwh-password
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_HOST=bastion.internal.example
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_PORT=22
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_USER=thoth_tunnel
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_PRIVATE_KEY_FILE=/run/secrets/north-star-research-dwh-tunnel-key
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_KNOWN_HOSTS_FILE=/run/secrets/north-star-research-dwh-known-hosts
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_TARGET_HOST=dwh.internal.example
|
||||
THT_WS_NORTH_STAR_RESEARCH_DWH_SSH_TARGET_PORT=5432
|
||||
```
|
||||
|
||||
Repeat SSH variables for `VECTOR` when selected. REST diagnostics refuse private per-request CAs
|
||||
@@ -138,15 +140,17 @@ The Git registry itself may still use SSH normally.
|
||||
|
||||
## Same-origin reverse proxy, bootstrap, and health
|
||||
|
||||
Copy [the server Compose example](examples/server-compose.workspace-registry.yaml) plus exactly one
|
||||
selected Git override to the protected operator directory. Set `THT_SOURCE_ROOT` to the absolute
|
||||
ThothII checkout; a copied file cannot use a relative build context. Copy
|
||||
`deploy/workspaces/server-sessions.yaml.example` into that operator directory, review it, then set
|
||||
the absolute `THT_SERVER_WORKSPACE_CONFIG` path. Copy the bindings env example, then set absolute
|
||||
`THT_WORKSPACE_BINDINGS_ENV_FILE` and connector `*_SOURCE` paths. The same `.env` must set
|
||||
Use the repository's canonical `compose.yaml` plus `deploy/compose.server.yaml`; they always
|
||||
start the mandatory `frontend` and `core` services. Do not copy or maintain a standalone
|
||||
application Compose file. Review `deploy/workspaces/server-sessions.yaml.example`, materialize it
|
||||
as a protected host file, and set its absolute `THT_SERVER_WORKSPACE_CONFIG` path. Copy the
|
||||
bindings env example into the operator directory, then set absolute `PI_AUTH_FILE`,
|
||||
`THT_SECRETS_FILE`, `THT_WORKSPACE_BINDINGS_ENV_FILE`, and connector `*_SOURCE` paths.
|
||||
The same operator env must set
|
||||
`THT_SESSION_DB_HOST`, `THT_SESSION_DB_NAME`, `THT_SESSION_RUNTIME_USER`,
|
||||
`THT_SESSION_RUNTIME_PASSWORD_SOURCE`, and `THT_SESSION_CA_SOURCE`; the base Compose file wires
|
||||
`postgres`, `verify-full`, and the two Docker secret mount paths. This is the public server profile,
|
||||
`THT_SESSION_RUNTIME_PASSWORD_SOURCE`, and `THT_SESSION_CA_SOURCE`;
|
||||
`deploy/compose.session-server.yaml.example` wires `postgres`, `verify-full`, and separate
|
||||
runtime/CA Docker secret mount paths. This is the public server profile,
|
||||
not a filesystem-session fallback. A Compose `.env` file is not a shell environment, so do not
|
||||
import it into the maintenance shell. Explicitly export the non-secret source and bindings paths
|
||||
before running the commands below.
|
||||
@@ -161,14 +165,24 @@ From a trusted maintenance shell:
|
||||
|
||||
```sh
|
||||
export THT_SOURCE_ROOT=/absolute/path/to/ThothII
|
||||
export THT_WORKSPACE_BINDINGS_ENV_FILE="$(pwd -P)/workspace-bindings.env"
|
||||
"$THT_SOURCE_ROOT/scripts/generate-connector-secrets-override.sh" --bindings-env "$THT_WORKSPACE_BINDINGS_ENV_FILE" --operator-env .env --output connector-secrets.local.yaml
|
||||
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file .env \
|
||||
-f compose.workspace-registry.yaml -f git-ssh.workspace-registry.yaml -f connector-secrets.local.yaml up --build -d
|
||||
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file .env \
|
||||
-f compose.workspace-registry.yaml -f git-ssh.workspace-registry.yaml -f connector-secrets.local.yaml exec -T core curl --fail --silent http://127.0.0.1:8787/health
|
||||
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file .env \
|
||||
-f compose.workspace-registry.yaml -f git-ssh.workspace-registry.yaml -f connector-secrets.local.yaml exec -T core curl --fail --silent http://127.0.0.1:8787/workspace-registry/status
|
||||
export THT_OPERATOR_ENV=/srv/thothii/operator/server.env
|
||||
export THT_WORKSPACE_BINDINGS_ENV_FILE=/srv/thothii/operator/workspace-bindings.env
|
||||
export THT_CONNECTOR_OVERRIDE=/srv/thothii/operator/connector-secrets.local.yaml
|
||||
"$THT_SOURCE_ROOT/scripts/generate-connector-secrets-override.sh" --bindings-env "$THT_WORKSPACE_BINDINGS_ENV_FILE" --operator-env "$THT_OPERATOR_ENV" --output "$THT_CONNECTOR_OVERRIDE"
|
||||
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file "$THT_OPERATOR_ENV" \
|
||||
-f "$THT_SOURCE_ROOT/compose.yaml" -f "$THT_SOURCE_ROOT/deploy/compose.server.yaml" \
|
||||
-f "$THT_SOURCE_ROOT/deploy/compose.session-server.yaml.example" \
|
||||
-f "$THT_SOURCE_ROOT/deploy/compose.git-ssh.yaml" -f "$THT_CONNECTOR_OVERRIDE" up --build -d
|
||||
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file "$THT_OPERATOR_ENV" \
|
||||
-f "$THT_SOURCE_ROOT/compose.yaml" -f "$THT_SOURCE_ROOT/deploy/compose.server.yaml" \
|
||||
-f "$THT_SOURCE_ROOT/deploy/compose.session-server.yaml.example" \
|
||||
-f "$THT_SOURCE_ROOT/deploy/compose.git-ssh.yaml" -f "$THT_CONNECTOR_OVERRIDE" \
|
||||
exec -T core curl --fail --silent http://127.0.0.1:8787/health
|
||||
"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file "$THT_OPERATOR_ENV" \
|
||||
-f "$THT_SOURCE_ROOT/compose.yaml" -f "$THT_SOURCE_ROOT/deploy/compose.server.yaml" \
|
||||
-f "$THT_SOURCE_ROOT/deploy/compose.session-server.yaml.example" \
|
||||
-f "$THT_SOURCE_ROOT/deploy/compose.git-ssh.yaml" -f "$THT_CONNECTOR_OVERRIDE" \
|
||||
exec -T core curl --fail --silent http://127.0.0.1:8787/workspace-registry/status
|
||||
```
|
||||
|
||||
`/health` is liveness. Registry status verifies branch/head/degraded state and the active validated
|
||||
@@ -187,7 +201,7 @@ filesystem-consistent backup of `/srv/thothii/workspace-registry` plus `/srv/tho
|
||||
`/srv/thothii/secrets`. Render Compose, deploy the compatible image, verify health/status, then
|
||||
resume proxy traffic.
|
||||
|
||||
For PSD migration, use a temporary review clone and the legacy transformer with absolute paths.
|
||||
For legacy descriptor migration, use a temporary review clone and the legacy transformer with absolute paths.
|
||||
Its schema-v1 output is `migration_required`; explicitly supply vector database/schema, collection
|
||||
identity, diagnostics, and the reviewed v2 contract before commit. Never import `${ENV}` values or
|
||||
copy secret files.
|
||||
|
||||
@@ -15,6 +15,8 @@ Servono Docker Engine/Compose v2 su Linux oppure Docker Desktop su macOS/Windows
|
||||
git clone <URL-REPOSITORY> ThothII
|
||||
cd ThothII
|
||||
cp deploy/env/local.env.example deploy/env/local.env
|
||||
cp deploy/secrets/thothii.secrets.example deploy/secrets/thothii.secrets
|
||||
chmod 600 deploy/secrets/thothii.secrets
|
||||
```
|
||||
|
||||
Modificare **solo** questi file interni al clone:
|
||||
@@ -25,7 +27,8 @@ Modificare **solo** questi file interni al clone:
|
||||
| file protetti locali | credenziali e certificati, indicati dai binding del workspace |
|
||||
| `deploy/workspaces/<nome>.yaml` | adapter, endpoint non riservati, `roots` ed Evidence |
|
||||
|
||||
Compilare `deploy/env/local.env`, incluso `PI_AUTH_FILE`, con gli endpoint esterni. L'avvio
|
||||
Compilare `deploy/env/local.env`, inclusi i path assoluti `PI_AUTH_FILE` e
|
||||
`THT_SECRETS_FILE`, con gli endpoint esterni. L'avvio
|
||||
normale usa esplicitamente il file base e l'overlay locale:
|
||||
|
||||
```sh
|
||||
@@ -52,7 +55,7 @@ THT_VECTOR_READER_PASSWORD=...
|
||||
THT_VECTOR_WRITER_PASSWORD=...
|
||||
```
|
||||
|
||||
Inserire solo le chiavi necessarie al profilo scelto. Il bundle viene montato in sola lettura nel container come `/run/secrets/thothii.secrets`; il parser rifiuta duplicati, chiavi sconosciute, valori vuoti, symlink e permessi host troppo aperti. Non inserire secret in `.env`, nei workspace, negli URL o nell'output di `docker compose config`.
|
||||
Inserire solo le chiavi necessarie al profilo scelto. Il bundle viene montato in sola lettura nel container come `/run/secrets/thothii.secrets`; il parser rifiuta duplicati, chiavi sconosciute, valori vuoti, symlink e permessi host troppo aperti. Non inserire secret in `.env`, nei workspace, negli URL o nell'output Compose renderizzato.
|
||||
|
||||
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.
|
||||
|
||||
@@ -62,7 +65,8 @@ DWH/vector/embedding remoti restano endpoint del file locale o server. Per il so
|
||||
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.
|
||||
poi ripetere l'intero comando base con l'azione `run --rm preprocess-evidence` oppure
|
||||
`run --rm preprocess-dwh`.
|
||||
|
||||
## Workspace, adapter e Evidence
|
||||
|
||||
@@ -124,8 +128,10 @@ THOTH_PUBLIC_EXPOSURE=false
|
||||
Riempire nel bundle le chiavi DWH/vector/model necessarie e avviare:
|
||||
|
||||
```sh
|
||||
docker compose up --build -d
|
||||
docker compose exec core /opt/venv/bin/tht doctor --json
|
||||
docker compose --env-file deploy/env/local.env \
|
||||
-f compose.yaml -f deploy/compose.local.yaml up --build -d
|
||||
docker compose --env-file deploy/env/local.env \
|
||||
-f compose.yaml -f deploy/compose.local.yaml exec core /opt/venv/bin/tht doctor --json
|
||||
```
|
||||
|
||||
Se si abilita l'overlay production, il proxy autenticato TLS deve essere l'unico listener pubblico
|
||||
@@ -159,7 +165,10 @@ THT_VECTOR_READER_PASSWORD=<valore casuale>
|
||||
THT_VECTOR_WRITER_PASSWORD=<valore casuale>
|
||||
```
|
||||
|
||||
Poi eseguire il comando standard `docker compose up --build -d`. Il primo avvio esegue reconciliation dei ruoli e migrazione pgvector. Per preprocessing, impostare il preset indicato sopra e usare `docker compose run --rm preprocess-evidence`/`preprocess-dwh`.
|
||||
Poi eseguire il comando standard base+locale mostrato sopra. Il primo avvio esegue
|
||||
reconciliation dei ruoli e migrazione pgvector. Per preprocessing, impostare il preset indicato
|
||||
sopra e usare l'azione `run --rm preprocess-evidence` o `run --rm preprocess-dwh` con tutti
|
||||
gli stessi file e profili.
|
||||
|
||||
## 3. PC Windows locale
|
||||
|
||||
@@ -175,8 +184,8 @@ THT_DOCS_ROOT=/data/source/evidence
|
||||
Creare `deploy/secrets/thothii.secrets` con un editor locale protetto (ACL leggibile solo dall'utente Docker) e le stesse quattro chiavi pgvector del profilo Mac. Non usare `ConvertFrom-SecureString`: il bundle deve contenere il valore in chiaro per il servizio, con accesso limitato al file. Da PowerShell, dalla radice del clone, eseguire:
|
||||
|
||||
```powershell
|
||||
docker compose up --build -d
|
||||
docker compose ps
|
||||
docker compose --env-file deploy/env/local.env -f compose.yaml -f deploy/compose.local.yaml up --build -d
|
||||
docker compose --env-file deploy/env/local.env -f compose.yaml -f deploy/compose.local.yaml ps
|
||||
```
|
||||
|
||||
Se un bind mount viene rifiutato, aggiungere la cartella del repository a Docker Desktop → Settings → Resources → File Sharing. Per Ollama eseguito in WSL2 usare l'indirizzo raggiungibile dalla rete Docker invece di assumere `localhost`.
|
||||
@@ -187,13 +196,25 @@ Usare il profilo server e consentire dal firewall solo le destinazioni necessari
|
||||
|
||||
```dotenv
|
||||
# Avvio: docker compose --env-file deploy/env/server.env \
|
||||
# -f compose.yaml -f deploy/compose.server.yaml up --build -d
|
||||
# -f compose.yaml -f deploy/compose.server.yaml \
|
||||
# -f deploy/compose.session-server.yaml.example up --build -d
|
||||
THT_DB_NAME=warehouse
|
||||
THT_DWH_REST_URL=https://dwh.example.test
|
||||
THT_VEC_REST_URL=https://vectors.example.test
|
||||
THT_OLLAMA_URL=https://embeddings.example.test
|
||||
```
|
||||
|
||||
Avviare e verificare con il profilo server completo:
|
||||
|
||||
```sh
|
||||
docker compose --env-file deploy/env/server.env \
|
||||
-f compose.yaml -f deploy/compose.server.yaml \
|
||||
-f deploy/compose.session-server.yaml.example up --build -d
|
||||
docker compose --env-file deploy/env/server.env \
|
||||
-f compose.yaml -f deploy/compose.server.yaml \
|
||||
-f deploy/compose.session-server.yaml.example exec core /opt/venv/bin/tht doctor --json
|
||||
```
|
||||
|
||||
Il DWH e il vector DB possono essere REST/HTTP oppure adapter diretti (`postgres_direct`, `pgvector_direct`) se il server ha connettività TCP. Le Evidence possono essere:
|
||||
|
||||
- filesystem NFS/SMB montato sul server e presentato come root read-only;
|
||||
@@ -208,8 +229,8 @@ Le variabili `THT_*_SECRET_FILE` e i file `dwh-api-key`, `vector-reader-api-key`
|
||||
|
||||
1. creare `deploy/secrets/thothii.secrets` mode `0600`;
|
||||
2. copiare ogni valore nel nome chiave corrispondente (`THT_DWH_API_KEY`, `THT_VEC_API_KEY`, `THT_VEC_WRITE_API_KEY`, `THT_MODEL_API_KEY` o `THT_VECTOR_*_PASSWORD`), senza virgolette né newline;
|
||||
3. rimuovere dal `.env` le variabili `_SECRET_FILE` e impostare `THT_SECRETS_FILE` al percorso del bundle (il default relativo è già corretto);
|
||||
4. eseguire `docker compose config --quiet` e poi `docker compose up --build -d`;
|
||||
3. rimuovere dal `.env` le variabili `_SECRET_FILE` e impostare `THT_SECRETS_FILE` al percorso assoluto del bundle;
|
||||
4. renderizzare e avviare con il comando base+locale completo e il suo `--env-file`;
|
||||
5. solo dopo la verifica, cancellare i vecchi file separati.
|
||||
|
||||
Una CA PEM resta un'eccezione esterna come descritto sopra. Provider Pi con credenziali composte (Bedrock, Azure OpenAI Responses, Cloudflare Workers AI/Gateway) restano rifiutati finché non viene implementato un adapter dedicato.
|
||||
@@ -217,9 +238,12 @@ Una CA PEM resta un'eccezione esterna come descritto sopra. Provider Pi con cred
|
||||
## Controlli post-installazione
|
||||
|
||||
```sh
|
||||
docker compose config --quiet
|
||||
docker compose ps
|
||||
docker compose exec core /opt/venv/bin/tht doctor --json
|
||||
docker compose --env-file deploy/env/local.env \
|
||||
-f compose.yaml -f deploy/compose.local.yaml config --quiet
|
||||
docker compose --env-file deploy/env/local.env \
|
||||
-f compose.yaml -f deploy/compose.local.yaml ps
|
||||
docker compose --env-file deploy/env/local.env \
|
||||
-f compose.yaml -f deploy/compose.local.yaml exec core /opt/venv/bin/tht doctor --json
|
||||
./scripts/docker-smoke.sh
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user