ThothII/README.md

ThothII

ThothII is a human-reviewed NL-to-SQL workflow with a React frontend and a Fastify/Pi/tht core. The portable deployment runs exactly two application services; data services remain external in this profile.

Docker Compose: external services

Requirements: Docker Engine with Compose v2 and reachable DWH, vector, and embeddings services.

1. For local development only, copy deploy/env.example to deploy/.env and fill in runtime credentials. The file is gitignored and is never copied into either image.

2. Add or edit YAML workspace descriptors under deploy/workspaces/. These files are mounted read-only. Use relative roots; they resolve beneath /data/workspaces/<workspace-name>.

3. Start the external-service profile:

   docker compose -f compose.yaml -f deploy/compose.local.yaml \
     --profile external up --build --wait
   

4. Open http://127.0.0.1:8080. The published port is loopback-only. Set THOTH_HTTP_PORT before starting to use another loopback port.

Application state, including settings, sessions, artifacts, and indexes, lives in the named thoth_data volume mounted at /data. docker compose down keeps that volume. Only an explicit destructive command such as docker compose down --volumes removes it.

The frontend depends on the core health check and proxies /health and /api/* to it. The application health endpoint intentionally checks process readiness only; external dependency diagnostics are exposed by tht doctor and do not prevent the UI from starting.

Run the end-to-end packaging check with:

./scripts/docker-smoke.sh

The smoke script validates Compose, builds and waits for both services, checks health through the frontend, verifies SSE response headers, restarts the core, and confirms /data survives. Each run uses a unique Compose project and removes that project's containers, network, and test volume afterward. It never targets the fixed thothii operator project or its volume. Set SMOKE_PROJECT to a different explicit project name for reproducible debugging, and set KEEP_SMOKE_RESOURCES=1 to retain that smoke project's resources for inspection; remove them later with docker compose --project-name "$SMOKE_PROJECT" --profile external down --volumes.

Production trust boundary and secrets

ThothII does not implement OIDC. Do not expose its application port directly to a network. The production pattern is an authenticated host reverse proxy that:

• terminates TLS and authenticates every request;
• removes any client-supplied identity header;
• injects one trusted X-Authenticated-User value;
• proxies to the loopback-only ThothII frontend.

deploy/nginx-authenticated-proxy.conf.example shows the contract using nginx auth_request; replace the placeholder authentication gateway with the organization's reviewed identity proxy. AUTH_MODE=upstream trusts this boundary and rejects requests without the identity header. Setting THOTH_PUBLIC_EXPOSURE=true with any other auth mode fails during core startup.

Production credentials use Compose secrets, not deploy/.env. Create four files outside the repository, restrict their host permissions, and point these variables to them:

export THT_DWH_API_KEY_SECRET_FILE=/secure/thoth/dwh-api-key
export THT_VEC_API_KEY_SECRET_FILE=/secure/thoth/vector-reader-api-key
export THT_VEC_WRITE_API_KEY_SECRET_FILE=/secure/thoth/vector-writer-api-key
export THT_CA_SECRET_FILE=/secure/thoth/ca-chain.pem
export THT_DB_NAME=warehouse
export THT_DWH_REST_URL=https://dwh.example.test
export THT_VEC_REST_URL=https://vectors.example.test
export THT_OLLAMA_URL=https://embeddings.example.test
docker compose -f compose.yaml -f deploy/compose.production.yaml \
  --profile external up --build --wait

The secrets and public CA chain are mounted read-only under /run/secrets and must be readable by the core's UID 10001. See deploy/secrets/README.md for the verification command. The frontend remains on loopback; the authenticated host proxy is the only public listener.

Reproducible image verification

Base images use exact tags and immutable multi-platform manifest digests. Dependency update and residual OS-repository limitations are documented in docker/LOCKS.md. Run the shared architecture gate with PLATFORM=linux/amd64 or PLATFORM=linux/arm64:

PLATFORM=linux/arm64 ./scripts/verify-container-images.sh

It builds both images, runs common version/runtime/security smokes, and emits an image/package inventory beneath .artifacts/container-images/. CI runs the same script for both architectures.