feat(deploy): add portable external-service stack

2026-07-11 22:12:21 +02:00
parent 715de6649b
commit 767df63a33
7 changed files with 265 additions and 1 deletions
@@ -0,0 +1,42 @@
+# 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:
+
+   ```sh
+   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:
+
+```sh
+./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.
+Its cleanup preserves the named volume.