docs(deploy): document user-owned session cutover

2026-07-16 19:02:58 +02:00
parent c6a74c9ccb
commit cadc4c6947
12 changed files with 441 additions and 2 deletions
@@ -0,0 +1,55 @@
+# Opt-in server overlay for user-owned PostgreSQL sessions. Copy this file to a
+# reviewed local override; it is intentionally not loaded by default Compose.
+services:
+  core:
+    environment:
+      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
+    secrets:
+      - source: session_runtime_password
+        target: session_runtime_password
+      - source: session_ca
+        target: session_ca.pem
+    volumes:
+      - ./deploy/workspaces:/app/harness/workspaces:ro
+
+  # Run manually during the maintenance window. It is not a dependency of core,
+  # so the application never gains the schema-changing migrator credential.
+  session-migrate:
+    image: thothii-core:local
+    profiles: [session-migrate]
+    entrypoint: [/bin/sh, -ec]
+    command: >-
+      export PGPASSWORD="$$(cat /run/secrets/session_migrator_password)";
+      exec /opt/venv/bin/tht session migrate --database-url
+      "postgresql+psycopg2://$${THT_SESSION_MIGRATOR_USER}@$${THT_SESSION_DB_HOST}:$${THT_SESSION_DB_PORT}/$${THT_SESSION_DB_NAME}?sslmode=$${THT_SESSION_DB_SSLMODE}&sslrootcert=/run/secrets/session_ca.pem"
+      --json
+    environment:
+      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_MIGRATOR_USER: ${THT_SESSION_MIGRATOR_USER:?set THT_SESSION_MIGRATOR_USER}
+      THT_SESSION_DB_SSLMODE: ${THT_SESSION_DB_SSLMODE:-verify-full}
+    secrets:
+      - source: session_migrator_password
+        target: session_migrator_password
+      - source: session_ca
+        target: session_ca.pem
+    restart: "no"
+
+secrets:
+  session_runtime_password:
+    file: ${THT_SESSION_RUNTIME_PASSWORD_SOURCE:?set THT_SESSION_RUNTIME_PASSWORD_SOURCE}
+  session_migrator_password:
+    file: ${THT_SESSION_MIGRATOR_PASSWORD_SOURCE:?set THT_SESSION_MIGRATOR_PASSWORD_SOURCE}
+  session_ca:
+    file: ${THT_SESSION_CA_SOURCE:?set THT_SESSION_CA_SOURCE}
@@ -14,6 +14,19 @@ PI_THINKING=
 MAX_PI_PROCESSES=4
 AUTH_MODE=none

+# User-owned session storage. Keep local for the loopback-only development stack.
+# The server-session overlay requires every THT_SESSION_* value below.
+THT_SESSION_STORAGE=local
+THT_SESSION_DB_HOST=
+THT_SESSION_DB_PORT=5432
+THT_SESSION_DB_NAME=
+THT_SESSION_RUNTIME_USER=
+THT_SESSION_RUNTIME_PASSWORD_SOURCE=
+THT_SESSION_MIGRATOR_USER=
+THT_SESSION_MIGRATOR_PASSWORD_SOURCE=
+THT_SESSION_DB_SSLMODE=verify-full
+THT_SESSION_CA_SOURCE=
+
 THT_DB_NAME=
 THT_DWH_REST_URL=
 THT_VEC_REST_URL=
@@ -43,3 +43,19 @@ password into `THT_VECTOR_BOOTSTRAP_PASSWORD` in the bundle before restarting
 Hosted Pi providers must use a single provider key. Compound providers (Bedrock, Azure OpenAI
 Responses, Cloudflare Workers AI/Gateway) fail closed until a provider-specific credential
 adapter is implemented.
+
+## User-owned session database secrets
+
+The server-session overlay deliberately does **not** add session database credentials to the
+shared bundle. Materialize three distinct Docker secrets from protected host or secret-manager
+files: `session_runtime_password`, `session_migrator_password`, and `session_ca.pem`. Their host
+source paths are respectively `THT_SESSION_RUNTIME_PASSWORD_SOURCE`,
+`THT_SESSION_MIGRATOR_PASSWORD_SOURCE`, and `THT_SESSION_CA_SOURCE`; all must be absolute paths
+outside the repository. The runtime password is mounted only into `core`; the migrator password
+is mounted only into the one-shot `session-migrate` service. Do not reuse either login for the
+other role.
+
+`session_ca.pem` is a PEM file rather than a bundle value because the bundle rejects whitespace.
+The server workspace receives only its mount path through `THT_SESSION_DB_SSLROOTCERT`; it uses
+`THT_SESSION_DB_SSLMODE=verify-ca` or, normally, `verify-full`. TLS disable/prefer/require modes
+are unsupported for session storage.
@@ -0,0 +1,36 @@
+# Copy to deploy/workspaces/server-sessions.yaml for the user-owned-session server profile.
+# The runtime login is intentionally separate from the one-shot migrator login.
+language: en
+
+dwh:
+  type: thoth_rest
+  database:
+    database: ${THT_DB_NAME}
+    schema: datawarehouse
+  endpoint:
+    base_url: ${THT_DWH_REST_URL}
+    api_key: ${THT_DWH_API_KEY}
+    ssl_ca: ${THT_SSL_CA}
+
+session_storage:
+  type: postgres_direct
+  connection:
+    host: ${THT_SESSION_DB_HOST}
+    port: ${THT_SESSION_DB_PORT}
+    database: ${THT_SESSION_DB_NAME}
+    schema: thoth_sessions
+    user: ${THT_SESSION_RUNTIME_USER}
+    password_file: ${THT_SESSION_RUNTIME_PASSWORD_FILE}
+    sslmode: ${THT_SESSION_DB_SSLMODE}
+    sslrootcert: ${THT_SESSION_DB_SSLROOTCERT}
+
+roots:
+  artifacts: artifacts
+  indexes: indexes
+  sessions: sessions
+
+embeddings:
+  base_url: ${THT_OLLAMA_URL}
+  model: nomic-embed-text-v2-moe
+  dim: 768
+  batch_size: 32