163 lines
6.4 KiB
Markdown
163 lines
6.4 KiB
Markdown
# 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
|
|
required.
|
|
|
|
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
|
|
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
|
|
choose **Save defaults**. The page shows credentials only as present or missing and can run bounded
|
|
diagnostics; it never accepts or displays a credential, opens a terminal, or updates an image.
|
|
|
|
Alternatively, use the CLI from an administrator terminal:
|
|
|
|
```sh
|
|
"$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
|
|
choices are restricted to supported models; non-interactive use must supply all three values. Both
|
|
methods store application defaults in backend installation settings, not in the project policy file.
|
|
|
|
Useful read-only checks are:
|
|
|
|
```sh
|
|
"$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.
|
|
|
|
## Edit the provider catalog and enabled-model policy
|
|
|
|
Edit these project-root files in source control, then review and deploy the change through the
|
|
normal project process:
|
|
|
|
- `deploy/pi/models.json` is the provider catalog: provider endpoints and the models each provider
|
|
offers.
|
|
- `deploy/pi/settings.json` is the enabled-model policy only; it lists the models available to the
|
|
application and does not store application defaults.
|
|
|
|
These files contain configuration, not credentials. Keep provider configuration declarative: Pi
|
|
management rejects executable `!command` values. Docker Compose mounts the selected configuration
|
|
and credential files read-only.
|
|
|
|
## Store provider credentials
|
|
|
|
`PI_AUTH_FILE` is a setting in the installation environment file (for example,
|
|
`deploy/env/local.env`). Its value is the absolute path of the protected host credential file that
|
|
this installation selects. Docker Compose mounts that selected file read-only for Pi.
|
|
Other declared protected material is likewise mounted read-only under `/run/secrets`.
|
|
|
|
Set restrictive permissions on the host file (`0600` on macOS/Linux or a user-only ACL on Windows).
|
|
Never put its contents in installation YAML, Git, command arguments, the browser, screenshots,
|
|
tickets, rendered Compose output, or logs. Do not print the file while troubleshooting.
|
|
|
|
## Reload changed configuration
|
|
|
|
After changing the provider catalog, enabled-model policy, or selected credential file, reload the
|
|
running application with one confirmed restart:
|
|
|
|
```sh
|
|
"$THTCTL" pi restart --yes --drain
|
|
```
|
|
|
|
`--yes` confirms that core will be recreated. Without `--drain`, restart refuses active sessions;
|
|
with it, ThothII closes admission and waits for active sessions to finish without terminating them.
|
|
The wait is bounded. Restart retains the exact captured running image: it does not build, pull, or
|
|
upgrade an image. Before recreating core, it pins that image through transaction-scoped Compose
|
|
override material so a configured tag moving during the operation cannot change the selected
|
|
image, and Compose is explicitly told never to build or pull. It will restart only core, then
|
|
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.
|
|
|
|
## Update the bundled Pi version
|
|
|
|
`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" 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" pi update \
|
|
--version 0.81.0 --source pull \
|
|
--image registry.example.invalid/thothii-core@sha256:<64-lowercase-hex-digits> \
|
|
--yes --drain
|
|
```
|
|
|
|
Update keeps new-session admission gated while it builds or pulls a candidate, recreates only
|
|
`core`, verifies it, and promotes the image only after success. It preserves the frontend and named
|
|
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,
|
|
containers, or volumes. Inspect status and sanitized logs:
|
|
|
|
```sh
|
|
"$THTCTL" pi maintenance status
|
|
"$THTCTL" pi status
|
|
"$THTCTL" pi logs
|
|
```
|
|
|
|
For a failed update, restore its prior image:
|
|
|
|
```sh
|
|
"$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" pi maintenance recover --yes
|
|
"$THTCTL" pi doctor
|
|
"$THTCTL" pi test
|
|
```
|
|
|
|
`pi rollback --yes` restores the prior update image. `pi maintenance recover --yes` checks both
|
|
restart and update recovery state before it can reopen admission. If either command fails, keep the
|
|
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.
|