146 lines
6.1 KiB
Markdown
146 lines
6.1 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.
|
|
|
|
In the commands below, replace `/absolute/path/to/thothii-installation.yaml` with the protected
|
|
installation descriptor created by the [local installation guide](local.md).
|
|
|
|
```sh
|
|
THTCTL=/absolute/path/to/thothctl
|
|
INSTALLATION=/absolute/path/to/thothii-installation.yaml
|
|
```
|
|
|
|
## 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" --installation "$INSTALLATION" pi configure
|
|
"$THTCTL" --installation "$INSTALLATION" 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" --installation "$INSTALLATION" pi status
|
|
"$THTCTL" --installation "$INSTALLATION" pi doctor
|
|
"$THTCTL" --installation "$INSTALLATION" pi test
|
|
"$THTCTL" --installation "$INSTALLATION" pi check
|
|
"$THTCTL" --installation "$INSTALLATION" 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" --installation "$INSTALLATION" 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 current image: it does not build, pull, select, or upgrade
|
|
an image. 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. Finish or drain
|
|
active work, then choose an explicit source and version. A build update uses this checkout:
|
|
|
|
```sh
|
|
"$THTCTL" --installation "$INSTALLATION" pi update \
|
|
--version 0.81.0 --source build --yes --drain
|
|
```
|
|
|
|
A registry update must use an immutable digest, never a mutable tag:
|
|
|
|
```sh
|
|
"$THTCTL" --installation "$INSTALLATION" 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. Do not delete `.thothctl`, state files, 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
|
|
```
|
|
|
|
For a failed update, restore its prior image:
|
|
|
|
```sh
|
|
"$THTCTL" --installation "$INSTALLATION" 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
|
|
```
|
|
|
|
`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.
|