From d82ebece4d3485720f309669122abdd0841606c9 Mon Sep 17 00:00:00 2001 From: mptyl Date: Tue, 4 Aug 2026 14:17:17 +0200 Subject: [PATCH] docs: design managed embedded pi operations --- ...08-04-unified-compose-deployment-design.md | 67 ++++++++++++++++++- 1 file changed, 65 insertions(+), 2 deletions(-) diff --git a/docs/superpowers/specs/2026-08-04-unified-compose-deployment-design.md b/docs/superpowers/specs/2026-08-04-unified-compose-deployment-design.md index ecc201da..8c11b6ce 100644 --- a/docs/superpowers/specs/2026-08-04-unified-compose-deployment-design.md +++ b/docs/superpowers/specs/2026-08-04-unified-compose-deployment-design.md @@ -121,6 +121,62 @@ Upgrading Pi requires changing the pinned build argument, rebuilding the image, normal ThothII regression and image-smoke gates. The container health/smoke test verifies that Pi exists in the image and can be invoked without any host executable. +## Pi management for non-technical operators + +Pi management uses a hybrid interface so an operator does not need Docker expertise while image +updates remain reproducible and recoverable. Configuration and diagnostics are available in a +ThothII “Pi Management” page; host lifecycle and upgrades are performed by a small ThothII control +command named `thothctl`. + +The Pi Management page shows the bundled Pi version, runtime state, configured provider, default +model and reasoning level, writable Pi-state location, and sanitized diagnostics. It supports +editing non-secret installation defaults, selecting only supported values, validating free-form +fields, testing provider credentials without displaying them, running a Pi smoke request, and +viewing sanitized logs. Per-user model/reasoning preferences remain browser-local until an +authentication system provides durable user identities; installation defaults and Pi runtime +configuration are stored in the mounted ThothII settings/Pi volumes. + +The page may report that a newer supported Pi version exists, but it does not control Docker and +does not mutate the package inside a running container. It presents the exact `thothctl pi update` +command appropriate to the installation. On a loopback-only single-user installation, the normal +configuration functions are available. On a server, privileged Pi management requires trusted +upstream authentication/authorization; without it, privileged controls are disabled and host-side +`thothctl` remains the only update path. + +`thothctl` provides the stable operator commands: + +```text +thothctl status +thothctl doctor +thothctl logs +thothctl update +thothctl backup +thothctl restore +thothctl pi status +thothctl pi doctor +thothctl pi configure +thothctl pi test +thothctl pi update +thothctl pi logs +``` + +The tool wraps validated Docker Compose operations and uses the same behavior on Windows, macOS, +and Linux. Distribution may use a small native executable or platform launchers, but command names, +prompts, exit codes, backups, and rollback semantics are identical. Interactive configuration asks +plain-language questions, offers closed choices where possible, writes only local non-secret +configuration, and directs credentials into protected secret files. + +`thothctl pi update` never runs `npm install` in the live container. It checks compatibility, +records the current image/configuration, builds or pulls an image containing the selected pinned Pi +version, recreates `core`, verifies health and `pi --version`, runs a smoke request, and rolls back +to the recorded image if verification fails. The update preserves `/data` and `/home/thoth/.pi` +volumes and prints a concise recovery result. + +For advanced support, documentation may expose `docker compose exec core pi ...`, but no browser +shell is enabled by default. The `core` container never mounts the Docker socket. A future updater +service or web-triggered image update requires a separate authenticated design and is outside this +scope. + ## Persistence Named volumes are the portable default for workstation installations. Server documentation shows @@ -204,6 +260,10 @@ Two complete guides are maintained against the same architecture: and secrets, local image build or pinned image use, startup, health, upgrade, rollback, backup, and recovery. +Both guides include a non-technical operator section for `thothctl`, Pi configuration, Pi upgrade, +failed-upgrade rollback, and obtaining sanitized diagnostic output for support. Windows examples +use native PowerShell commands or a packaged executable rather than assuming a Unix shell. + Both guides use copy-pastable commands validated by scripts. They explain which configuration is shared in Git, which is installation-local, and how a server that only provides DWH/VectorDB is consumed without installing ThothII there. @@ -214,8 +274,10 @@ Automated gates cover Compose rendering for local/server plus each Git transport Docker builds, container health, frontend-to-core same-origin routing, registry bootstrap and offline fallback, secret non-disclosure, and absence of PSD/Chirone/portal dependencies in active deployment files. Image tests also prove that the pinned Pi executable is available inside `core` -and that no host Pi path is mounted or required. Existing backend, frontend, harness, registry, and -installation-document tests remain required. +and that no host Pi path or Docker socket is mounted or required. Contract tests cover every +`thothctl pi` command, non-interactive exit codes, update rollback, volume preservation, secret +redaction, and parity of Windows/macOS/Linux launchers. Existing backend, frontend, harness, +registry, and installation-document tests remain required. Manual acceptance covers a clean macOS build, a clean Windows Docker Desktop/WSL2 build from a GitHub clone, a Linux server deployment behind a generic proxy, an update after `git pull`, volume @@ -228,3 +290,4 @@ persistence, and restoration from backup. - Making PSD, Chirone, or `omics_portal` supported product profiles. - Synchronizing local filesystem sessions between installations without shared session storage. - Implementing persistent runtime SSH tunnels for workspace connectors in this migration. +- Providing a browser terminal or allowing the application container to control the Docker daemon.