mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat: finish Pi and workspace management updates

Browse Source
This commit is contained in:
marcopan
2026-08-16 14:19:32 +02:00
parent 7651b63cea
commit 351361f72f
20 changed files with 2276 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/install/pi-management.md
+38 -24
View File
@@ -4,14 +4,21 @@ ThothII bundles Pi in the `core` image. Operators use the Pi Management page for
defaults and the host-side `thothctl` CLI for lifecycle work. A local Pi installation is not
required.
In the commands below, replace `/absolute/path/to/thothii-installation.yaml` with the protected
installation descriptor created by the [local installation guide](local.md).
Run these commands from the root of the current ThothII checkout or worktree. `thothctl` discovers
the valid installation descriptor in that project tree, so it uses the `deploy/` files belonging to
the checkout from which you run it. Do not use `~/bin`: `~` is the user home directory, not the
project root.
```sh
THTCTL=/absolute/path/to/thothctl
INSTALLATION=/absolute/path/to/thothii-installation.yaml
mkdir -p bin
go -C tools/thothctl build -o ../../bin/thothctl ./cmd/thothctl
THTCTL=./bin/thothctl
```
If `thothctl` is already on `PATH`, you may use `THTCTL=thothctl` instead. For an installation
stored elsewhere, set `THOTHII_INSTALLATION` or pass
`--installation <absolute-path>/thothii-installation.yaml` explicitly.
## Choose application defaults
Use the **Pi Management** page to select the supported provider, model, and reasoning default, then
@@ -21,8 +28,8 @@ diagnostics; it never accepts or displays a credential, opens a terminal, or upd
Alternatively, use the CLI from an administrator terminal:
```sh
"$THTCTL" --installation "$INSTALLATION" pi configure
"$THTCTL" --installation "$INSTALLATION" pi configure --provider zai --model glm-5.2 --thinking medium
"$THTCTL" pi configure
"$THTCTL" pi configure --provider zai --model glm-5.2 --thinking medium
```
Use GUI Save defaults or CLI `pi configure`, not both for the same change. The CLI's interactive
@@ -32,11 +39,11 @@ methods store application defaults in backend installation settings, not in the
Useful read-only checks are:
```sh
"$THTCTL" --installation "$INSTALLATION" pi status
"$THTCTL" --installation "$INSTALLATION" pi doctor
"$THTCTL" --installation "$INSTALLATION" pi test
"$THTCTL" --installation "$INSTALLATION" pi check
"$THTCTL" --installation "$INSTALLATION" pi logs
"$THTCTL" pi status
"$THTCTL" pi doctor
"$THTCTL" pi test
"$THTCTL" pi check
"$THTCTL" pi logs
```
`pi check` is an alias for `pi test`; logs are a sanitized, bounded snapshot with no follow mode.
@@ -72,7 +79,7 @@ After changing the provider catalog, enabled-model policy, or selected credentia
running application with one confirmed restart:
```sh
"$THTCTL" --installation "$INSTALLATION" pi restart --yes --drain
"$THTCTL" pi restart --yes --drain
```
`--yes` confirms that core will be recreated. Without `--drain`, restart refuses active sessions;
@@ -89,18 +96,25 @@ and `thothctl start` or raw Compose commands for this reload workflow.
## Update the bundled Pi version
`pi update` is for a new bundled Pi version; it is not a configuration reload. Finish or drain
active work, then choose an explicit source and version. A build update uses this checkout:
`pi update` is for a new bundled Pi version; it is not a configuration reload. The simple command
uses the single `ARG PI_VERSION=...` pin in `docker/core.Dockerfile`, builds that version, waits for
active sessions to finish, and recreates only `core`:
```sh
"$THTCTL" --installation "$INSTALLATION" pi update \
--version 0.81.0 --source build --yes --drain
"$THTCTL" pi update
```
To build a specific version, pass `--version`; source, confirmation, and drain are automatic for
this normal build path:
```sh
"$THTCTL" pi update --version 0.81.0
```
A registry update must use an immutable digest, never a mutable tag:
```sh
"$THTCTL" --installation "$INSTALLATION" pi update \
"$THTCTL" pi update \
--version 0.81.0 --source pull \
--image registry.example.invalid/thothii-core@sha256:<64-lowercase-hex-digits> \
--yes --drain
@@ -117,24 +131,24 @@ reported recovery state and transaction override. Do not delete `.thothctl`, sta
containers, or volumes. Inspect status and sanitized logs:
```sh
"$THTCTL" --installation "$INSTALLATION" pi maintenance status
"$THTCTL" --installation "$INSTALLATION" pi status
"$THTCTL" --installation "$INSTALLATION" pi logs
"$THTCTL" pi maintenance status
"$THTCTL" pi status
"$THTCTL" pi logs
```
For a failed update, restore its prior image:
```sh
"$THTCTL" --installation "$INSTALLATION" pi rollback --yes
"$THTCTL" pi rollback --yes
```
For a failed restart, use maintenance recovery instead of rollback. After repairing the reported
Docker, disk, or configuration problem, use the same command to complete either safe recovery path:
```sh
"$THTCTL" --installation "$INSTALLATION" pi maintenance recover --yes
"$THTCTL" --installation "$INSTALLATION" pi doctor
"$THTCTL" --installation "$INSTALLATION" pi test
"$THTCTL" pi maintenance recover --yes
"$THTCTL" pi doctor
"$THTCTL" pi test
```
`pi rollback --yes` restores the prior update image. `pi maintenance recover --yes` checks both