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. Copy deploy/env.example to deploy/.env and fill in runtime credentials. The .env file is gitignored and is read only when the container starts; secrets are 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 --profile external up --build --wait
   

4. Open http://localhost:8080. Set THOTH_HTTP_PORT before starting to use another host 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.