144 lines
6.1 KiB
Markdown
144 lines
6.1 KiB
Markdown
# Pi management
|
|
|
|
Pi is pinned inside the ThothII `core` image. A local Pi, Node.js, Python, or Go installation is
|
|
not required. The browser can manage safe runtime settings, while the host-side `thothctl`
|
|
operator CLI performs container lifecycle and image updates. The core does not mount the Docker socket,
|
|
and there is no browser shell.
|
|
|
|
In the commands below, replace `/absolute/path/to/thothii-installation.yaml` with the protected
|
|
installation descriptor created by the [local installation guide](local.md).
|
|
|
|
## Who can use Pi Management
|
|
|
|
On the loopback-only local profile (`AUTH_MODE=none`), the person using that PC can open Pi
|
|
Management and change installation defaults or run diagnostics. Do not expose ports 8080 or 8787
|
|
to another machine.
|
|
|
|
On a public server, Pi Management requires upstream authentication and a trusted administrator
|
|
claim supplied by the authenticated reverse proxy. Without that claim the API returns
|
|
`403 pi_management_forbidden`; ordinary users cannot change installation-wide Pi settings. Image
|
|
updates are never available from the web page on either profile.
|
|
|
|
## Use the Pi Management page
|
|
|
|
Open ThothII, choose **Pi Management**, and check the bundled version and readiness. The page:
|
|
|
|
- offers only supported provider, model, and reasoning choices;
|
|
- saves non-secret defaults;
|
|
- reports credentials only as present or missing;
|
|
- runs a bounded provider smoke test; and
|
|
- shows at most 200 sanitized log lines.
|
|
|
|
It never displays or accepts a credential, runs an image update, or opens a terminal. Per-user
|
|
browser preferences remain separate from installation defaults.
|
|
|
|
## Use thothctl
|
|
|
|
Set a short shell variable for the platform-specific executable. Examples below use macOS/Linux:
|
|
|
|
```sh
|
|
THTCTL=/absolute/path/to/thothctl
|
|
INSTALLATION=/absolute/path/to/thothii-installation.yaml
|
|
```
|
|
|
|
The complete Pi command set is:
|
|
|
|
```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 configure
|
|
"$THTCTL" --installation "$INSTALLATION" pi configure --provider zai --model glm-5.2 --thinking medium
|
|
"$THTCTL" --installation "$INSTALLATION" pi logs
|
|
"$THTCTL" --installation "$INSTALLATION" pi maintenance status
|
|
```
|
|
|
|
- `pi status` reads the image-bundled version.
|
|
- `pi doctor` checks the version boundaries, core health, settings, and configured model.
|
|
- `pi test` runs the isolated Pi/core smoke; `pi check` is its alias.
|
|
- `pi configure` presents closed choices on a terminal. Non-interactive use requires all three
|
|
flags. Never pass a credential as an argument.
|
|
- `pi logs` returns a bounded, sanitized snapshot and deliberately has no follow mode.
|
|
- `pi maintenance status` reports whether new session admission is gated.
|
|
|
|
Use `thothctl status`, `doctor`, `logs`, `start`, `stop`, and `update --check-only` for the wider
|
|
installation. Direct Compose lifecycle commands can bypass the durable image selector and are not
|
|
the normal operator interface.
|
|
|
|
## Handle credentials and secrets
|
|
|
|
Keep provider credentials in the protected host file named by `PI_AUTH_FILE`, or in the documented
|
|
model secret file/bundle. Compose mounts protected material read-only under `/run/secrets` or at
|
|
Pi's protected auth path. Apply mode `0600` on macOS/Linux or a user-only ACL on Windows.
|
|
|
|
Never put secret text in the installation YAML, operator environment, workspace Git repository,
|
|
command arguments, browser, screenshots, tickets, rendered Compose, or logs. Pi configuration is
|
|
declarative: executable `!command` values are rejected. Use supported environment references or
|
|
the protected credential files.
|
|
|
|
After rotating a credential, restart core through `thothctl stop` and `thothctl start`, then run
|
|
`pi doctor` and `pi test`. Do not print the file while troubleshooting.
|
|
|
|
## Update and roll back Pi
|
|
|
|
Finish or close active work first. A build update uses source already present in 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
|
|
```
|
|
|
|
The operation gates new sessions, records non-secret recovery state, recreates only `core`, checks
|
|
the requested version, health, settings, smoke request, configuration, and persistence mounts,
|
|
then promotes the verified image. Frontend and named volumes are preserved.
|
|
|
|
To restore the image recorded by the interrupted or latest update:
|
|
|
|
```sh
|
|
"$THTCTL" --installation "$INSTALLATION" pi rollback --yes
|
|
```
|
|
|
|
## Recover a failed update
|
|
|
|
Do not delete `.thothctl`, `update-state.json`, `current-image.yaml`, containers, or volumes. First
|
|
inspect the durable gate and sanitized logs:
|
|
|
|
```sh
|
|
"$THTCTL" --installation "$INSTALLATION" pi maintenance status
|
|
"$THTCTL" --installation "$INSTALLATION" pi logs
|
|
"$THTCTL" --installation "$INSTALLATION" pi rollback --yes
|
|
```
|
|
|
|
If rollback reports a terminal or stale maintenance state, repair the reported Docker, disk, or
|
|
configuration problem, then run:
|
|
|
|
```sh
|
|
"$THTCTL" --installation "$INSTALLATION" pi maintenance recover --yes
|
|
"$THTCTL" --installation "$INSTALLATION" pi doctor
|
|
"$THTCTL" --installation "$INSTALLATION" pi test
|
|
```
|
|
|
|
If recovery still fails, leave maintenance active and preserve the recovery file. Collect only
|
|
sanitized `pi logs`, `status`, and `doctor` output for support; do not ungate the installation by
|
|
editing state files.
|
|
|
|
## Direct support access
|
|
|
|
Advanced support may inspect the bundled executable directly with the installation's exact
|
|
validated Compose file set, for example `docker compose exec core pi --version`. This is read-only
|
|
diagnosis, not an update mechanism. Do not run package installers, alter Pi files inside the live
|
|
container, mount the Docker socket, expose a browser shell, or use a host Pi as a substitute.
|
|
|
|
Prefer `thothctl pi status`, `pi doctor`, `pi test`, and `pi logs`, because they include the durable
|
|
image selector and redact declared secret values. Share only their sanitized output.
|