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

docs: converge operator guidance on tht

Browse Source
This commit is contained in:
marcopan
2026-08-19 16:12:11 +02:00
parent 32a17d83a9
commit 1184b6db16
29 changed files with 544 additions and 380 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/install/pi-management.md
+29 -29
View File
@@ -1,21 +1,21 @@
# Pi management
ThothII bundles Pi in the `core` image. Operators use the Pi Management page for safe application
defaults and the host-side `thothctl` CLI for lifecycle work. A local Pi installation is not
defaults and the host-side `tht` CLI for lifecycle work. A local Pi installation is not
required.
Run these commands from the root of the current ThothII checkout or worktree. `thothctl` discovers
Run these commands from the root of the current ThothII checkout or worktree. `tht` 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
mkdir -p bin
go -C tools/thothctl build -o ../../bin/thothctl ./cmd/thothctl
THTCTL=./bin/thothctl
THT_BIN=tht
tht version --json
```
If `thothctl` is already on `PATH`, you may use `THTCTL=thothctl` instead. For an installation
If `tht` is not on `PATH`, install the native host CLI using the installation procedure in
`local.md` or `server.md`, then set `THT_BIN` to that installed binary. For an installation
stored elsewhere, set `THOTHII_INSTALLATION` or pass
`--installation <absolute-path>/thothii-installation.yaml` explicitly.
@@ -28,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" pi configure
"$THTCTL" pi configure --provider zai --model glm-5.2 --thinking medium
"$THT_BIN" pi configure
"$THT_BIN" 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
@@ -39,11 +39,11 @@ methods store application defaults in backend installation settings, not in the
Useful read-only checks are:
```sh
"$THTCTL" pi status
"$THTCTL" pi doctor
"$THTCTL" pi test
"$THTCTL" pi check
"$THTCTL" pi logs
"$THT_BIN" pi status
"$THT_BIN" pi doctor
"$THT_BIN" pi test
"$THT_BIN" pi check
"$THT_BIN" pi logs
```
`pi check` is an alias for `pi test`; logs are a sanitized, bounded snapshot with no follow mode.
@@ -79,7 +79,7 @@ After changing the provider catalog, enabled-model policy, or selected credentia
running application with one confirmed restart:
```sh
"$THTCTL" pi restart --yes --drain
"$THT_BIN" pi restart --yes --drain
```
`--yes` confirms that core will be recreated. Without `--drain`, restart refuses active sessions;
@@ -91,8 +91,8 @@ image, and Compose is explicitly told never to build or pull. It will restart on
verifies health, Pi version, settings/model smoke, non-secret rendered configuration, and
persistence mounts before reopening admission.
Use `pi restart --yes` when there are already no active sessions. Do not substitute `thothctl stop`
and `thothctl start` or raw Compose commands for this reload workflow.
Use `pi restart --yes` when there are already no active sessions. Do not substitute `tht stop`
and `tht start` or raw Compose commands for this reload workflow.
## Update the bundled Pi version
@@ -101,20 +101,20 @@ uses the single `ARG PI_VERSION=...` pin in `docker/core.Dockerfile`, builds tha
active sessions to finish, and recreates only `core`:
```sh
"$THTCTL" pi update
"$THT_BIN" 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
"$THT_BIN" pi update --version 0.81.0
```
A registry update must use an immutable digest, never a mutable tag:
```sh
"$THTCTL" pi update \
"$THT_BIN" pi update \
--version 0.81.0 --source pull \
--image registry.example.invalid/thothii-core@sha256:<64-lowercase-hex-digits> \
--yes --drain
@@ -127,28 +127,28 @@ volumes.
## Recover a failed lifecycle operation
If a restart or update fails after core recreation, leave maintenance enabled and preserve the
reported recovery state and transaction override. Do not delete `.thothctl`, state files,
reported recovery state and transaction override. Do not delete `.tht`, state files,
containers, or volumes. Inspect status and sanitized logs:
```sh
"$THTCTL" pi maintenance status
"$THTCTL" pi status
"$THTCTL" pi logs
"$THT_BIN" pi maintenance status
"$THT_BIN" pi status
"$THT_BIN" pi logs
```
For a failed update, restore its prior image:
```sh
"$THTCTL" pi rollback --yes
"$THT_BIN" 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" pi maintenance recover --yes
"$THTCTL" pi doctor
"$THTCTL" pi test
"$THT_BIN" pi maintenance recover --yes
"$THT_BIN" pi doctor
"$THT_BIN" pi test
```
`pi rollback --yes` restores the prior update image. `pi maintenance recover --yes` checks both
@@ -158,5 +158,5 @@ installation gated and collect only the sanitized diagnostics.
## Direct support access
Raw Compose access is unsupported because it can bypass the installation-specific environment and
durable image selector. For support, use the installation-aware `thothctl pi status`,
`thothctl pi doctor`, `thothctl pi test`, and `thothctl pi logs` commands.
durable image selector. For support, use the installation-aware `tht pi status`,
`tht pi doctor`, `tht pi test`, and `tht pi logs` commands.