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

docs: clarify Pi reload and update workflows

Browse Source
This commit is contained in:
marcopan
2026-08-14 18:34:04 +02:00
parent 59a04123ea
commit a8623a2b18
4 changed files with 147 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/thothctl-pi.md
+47 -13
View File
@@ -65,6 +65,37 @@ this protection and are unsupported. Advanced documented Compose rendering must
`scripts/compose-with-preflight.sh` and include the same selector with `-f` when present; connector
secret overrides must never bypass that preflight wrapper.
## Reloading Pi configuration
Configuration reload is a separate lifecycle operation from an image update:
```text
thothctl --installation /absolute/path/thothii-installation.yaml pi restart --yes [--drain]
```
`--yes` is required after reviewing the planned core recreation. Restart activates the durable
maintenance gate before it checks sessions. Without `--drain`, active open sessions refuse the
command. With `--drain`, the command polls the authenticated session inventory until no active
sessions remain; it never terminates sessions and the wait is bounded.
Restart retains the exact current image and does not build, pull, select, tag, or upgrade an image.
It recreates only `core` with `--no-deps --force-recreate`; `frontend` and named volumes are not
recreated. Before reopening admission, it verifies health, the unchanged Pi version, the
provider/model/settings smoke, unchanged non-secret rendered configuration, the current image
identity, and the complete persistence-mount fingerprint.
Restart and update keep separate recovery state:
```text
<projectDirectory>/.thothctl/<installation-id>/restart-state.json
<projectDirectory>/.thothctl/<installation-id>/update-state.json
```
The files are mode `0600` and share one installation lifecycle lock, so a restart cannot race an
update. A restart refuses an incomplete update or restart state. After core mutation, a failure
leaves admission gated and preserves `restart-state.json`; the operator must use status/logs and
maintenance recovery rather than deleting state files.
## Updating Pi
Every update requires a pinned version, an explicit source, and confirmation:
@@ -117,14 +148,16 @@ Recovery state and lock diagnostics live under:
```text
<projectDirectory>/.thothctl/<installation-id>/update-state.json
<projectDirectory>/.thothctl/<installation-id>/update-state.json.lock.owner.json
<projectDirectory>/.thothctl/<installation-id>/restart-state.json
<projectDirectory>/.thothctl/<installation-id>/*.lock.owner.json
```
The recovery file is mode `0600` and records transaction-scoped image identities, mount
fingerprints, target version/source, configuration digest, phase, and timestamp. It contains no
credentials, endpoint values, secret paths, Compose output, or logs. A cross-platform OS advisory
file lock serializes lifecycle operations; a crashed owner releases the lock automatically. Owner
metadata is diagnostic only and cannot wedge acquisition if empty, partial, or stale.
Each recovery file is mode `0600`. Update state records transaction-scoped image identities, mount
fingerprints, target version/source, configuration digest, phase, and timestamp; restart state
records the retained image and its verification inputs. Neither file contains credentials, endpoint
values, secret paths, Compose output, or logs. A cross-platform OS advisory file lock serializes
both lifecycle operations; a crashed owner releases the lock automatically. Owner metadata is
diagnostic only and cannot wedge acquisition if empty, partial, or stale.
Any post-candidate failure explicitly confirms or reactivates maintenance and rescans sessions
before compensation. Automatic rollback selects the transaction's previous image through the
@@ -149,13 +182,14 @@ thothctl --installation /absolute/path/thothii-installation.yaml pi maintenance
thothctl --installation /absolute/path/thothii-installation.yaml pi maintenance recover --yes
```
`maintenance recover` completes an interrupted verified-image promotion, safely finalizes a
preparation interrupted before core mutation, and refuses other pending mutations. For terminal or
absent recovery state, it removes only a stale transaction override, verifies the running
installation when the gate is active, and only then removes the durable marker and reopens
admission. It never removes `current-image.yaml`. If rollback or recovery fails, leave the marker
in place, preserve `update-state.json`, repair the reported Docker/configuration issue, and rerun
rollback or maintenance recovery.
`maintenance recover` verifies and removes an interrupted restart state before it processes update
state. It completes an interrupted verified-image promotion, safely finalizes a preparation
interrupted before core mutation, and refuses other pending mutations. For terminal or absent
recovery state, it removes only a stale transaction override, verifies the running installation
when the gate is active, and only then removes the durable marker and reopens admission. It never
removes `current-image.yaml`. If rollback or recovery fails, leave the marker in place, preserve
the relevant recovery state, repair the reported Docker/configuration issue, and rerun rollback or
maintenance recovery.
Missing confirmation, invalid arguments, active sessions, and an interrupted transaction exit
`2`. Docker and verification failures exit nonzero with concise, redacted guidance. Direct