ThothII/docs/superpowers/specs/2026-07-12-local-and-server-docker-deployment-design.md

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.