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

docs: correct Pi operator recovery guidance

Browse Source
This commit is contained in:
marcopan
2026-08-14 18:41:34 +02:00
parent a8623a2b18
commit dc83a55555
3 changed files with 28 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/install/pi-management.md
+16 -11
View File
@@ -2,7 +2,7 @@
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; the core container does not mount the Docker socket and there is no browser shell.
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).
@@ -26,7 +26,8 @@ Alternatively, use the CLI from an administrator terminal:
```
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.
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:
@@ -47,11 +48,12 @@ 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 and application defaults.
- `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. Do not edit generated files, the running
container, or a host-native Pi directory.
management rejects executable `!command` values. Docker Compose mounts the selected configuration
and credential files read-only.
## Store provider credentials
@@ -109,17 +111,22 @@ volumes.
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, then restore the previous image when an update is involved:
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
```
Repair the reported Docker, disk, or configuration problem, then have ThothII complete the safe
recovery path:
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
@@ -135,6 +142,4 @@ installation gated and collect only the sanitized diagnostics.
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. Do not run package
installers, alter files inside the live container, mount the Docker socket, expose a browser shell,
or use a host Pi as a substitute.
`thothctl pi doctor`, `thothctl pi test`, and `thothctl pi logs` commands.