docs: define local and server Docker deployment

2026-07-12 16:27:05 +02:00
parent f67d2c97d8
commit c446d40e1f
1 changed files with 34 additions and 0 deletions
@@ -0,0 +1,34 @@
+# Local and Server Docker Deployment Design
+
+## Goal
+
+Run ThothII locally in Docker against the existing PSD services, while keeping the
+same tracked Docker package deployable on a server hosting the DWH and pgvector.
+
+## Decisions
+
+- `compose.yaml` remains portable and contains no customer paths, credentials, or
+  private certificate material.
+- The GLM registry is a tracked, non-secret Pi configuration. The provider key is
+  supplied only through the existing Docker secret bundle.
+- A local-only Compose override binds the existing PSD workspace and CA material
+  from the developer machine. It is ignored by Git and exists solely to validate
+  Docker Desktop against the real workflow.
+- A server profile consumes its own workspace mount, secret bundle, and service
+  endpoints. It never relies on macOS paths or a developer's `~/.pi` directory.
+- The verification scope is a live session start through Pi using `zai/glm-5.2`;
+  it stops at the first human-review gate and does not finalize a datamart.
+
+## Configuration Boundaries
+
+Tracked files define images, Compose service contracts, templates, validation, and
+documentation. Ignored runtime files hold the selected endpoint values, secret
+bundle, certificate mount source, and local workspace path. The server receives
+only the tracked package; its operator materializes equivalent runtime files with
+server-specific values.
+
+## Validation
+
+The local run must validate Compose syntax, image builds, secret mount readability,
+core/frontend health endpoints, model discovery, session creation, and receipt of a
+Pi workflow event. Failure diagnostics must omit secret values.