docs: add live Colibri rebuild runbook (Sam & Codex)
Document how a running live USB can clone, build, install, and validate Colibri without a full ISO rebuild, plus the future helper-script shape.\n\nChecks: npx --yes prettier@3 --check docs/LIVE-COLIBRI-REBUILD.md; git diff --check. Note: ./scripts/check-format.sh still reports existing PLAN-OPERATOR-USB-NEXT.md formatting drift outside this change.
This commit is contained in:
parent
45dd9274d9
commit
54c92d5993
1 changed files with 225 additions and 0 deletions
225
docs/LIVE-COLIBRI-REBUILD.md
Normal file
225
docs/LIVE-COLIBRI-REBUILD.md
Normal file
|
|
@ -0,0 +1,225 @@
|
|||
# Live USB Colibri rebuild lane
|
||||
|
||||
This runbook documents how a running Clawdie live USB can rebuild and redeploy
|
||||
Colibri without waiting for a full ISO rebuild.
|
||||
|
||||
Use this for **field repair and validation** when the USB boots but a Colibri
|
||||
binary, rc.d script, or small runtime behavior needs testing. A successful live
|
||||
rebuild does **not** replace the release ISO process; it proves the fix before
|
||||
the next image is rebuilt.
|
||||
|
||||
## Why this exists
|
||||
|
||||
The live USB currently stages `/home/clawdie/ai/colibri` as a source snapshot
|
||||
from `git archive`. That snapshot is useful for inspection, but it is not a real
|
||||
git checkout and has no `.git` directory:
|
||||
|
||||
```sh
|
||||
cd /home/clawdie/ai/colibri
|
||||
git remote -v
|
||||
# fatal: not a git repository (or any of the parent directories): .git
|
||||
```
|
||||
|
||||
For rebuilds, clone a fresh working checkout into a separate directory such as
|
||||
`/home/clawdie/ai/colibri-build` or `/var/tmp/colibri-build`.
|
||||
|
||||
## Required live packages
|
||||
|
||||
Future ISOs should include these packages to make this path available out of the
|
||||
box:
|
||||
|
||||
```text
|
||||
rust
|
||||
pkgconf
|
||||
git
|
||||
```
|
||||
|
||||
`git` is already in the live operator package list. `rust` provides `cargo` on
|
||||
FreeBSD. `pkgconf` is needed by common Rust native dependency build scripts.
|
||||
|
||||
Optional if future dependencies need them:
|
||||
|
||||
```text
|
||||
gmake
|
||||
cmake
|
||||
```
|
||||
|
||||
## One-time readiness check
|
||||
|
||||
Run on the live USB:
|
||||
|
||||
```sh
|
||||
rustc --version
|
||||
cargo --version
|
||||
git --version
|
||||
pkgconf --version
|
||||
```
|
||||
|
||||
If `rustc` or `cargo` is missing, the current USB cannot rebuild Colibri from
|
||||
source without installing packages first or using a newer ISO.
|
||||
|
||||
## Clone or update Colibri
|
||||
|
||||
Use HTTPS unless the live USB has an SSH key configured for Forgejo.
|
||||
|
||||
```sh
|
||||
mkdir -p /home/clawdie/ai
|
||||
cd /home/clawdie/ai
|
||||
|
||||
if [ ! -d colibri-build/.git ]; then
|
||||
git clone https://code.smilepowered.org/clawdie/colibri.git colibri-build
|
||||
fi
|
||||
|
||||
cd /home/clawdie/ai/colibri-build
|
||||
git fetch --prune origin
|
||||
git switch main
|
||||
git pull --ff-only
|
||||
```
|
||||
|
||||
To test a specific commit or branch:
|
||||
|
||||
```sh
|
||||
git checkout c967698
|
||||
# or:
|
||||
# git switch fix/some-branch
|
||||
```
|
||||
|
||||
## Build Colibri release binaries
|
||||
|
||||
Minimal live USB build set:
|
||||
|
||||
```sh
|
||||
cd /home/clawdie/ai/colibri-build
|
||||
cargo build --release \
|
||||
-p colibri-daemon \
|
||||
-p colibri-client \
|
||||
-p colibri-mcp \
|
||||
-p colibri-glasspane-tui
|
||||
```
|
||||
|
||||
Expected outputs:
|
||||
|
||||
```text
|
||||
target/release/colibri-daemon
|
||||
target/release/colibri
|
||||
target/release/colibri-smoke-agent
|
||||
target/release/colibri-mcp
|
||||
target/release/colibri-tui
|
||||
```
|
||||
|
||||
## Install rebuilt Colibri into the running USB
|
||||
|
||||
The live USB does not use `sudo`. Privileged actions use `mdo`.
|
||||
|
||||
```sh
|
||||
cd /home/clawdie/ai/colibri-build
|
||||
|
||||
mdo -u root service colibri_daemon stop || true
|
||||
mdo -u root pkill -f colibri-daemon || true
|
||||
mdo -u root rm -f /var/run/colibri/colibri.sock
|
||||
mdo -u root rm -f /var/run/colibri/colibri-daemon.pid
|
||||
mdo -u root rm -f /var/run/colibri/colibri-daemon-supervisor.pid
|
||||
|
||||
mdo -u root install -m 0555 target/release/colibri-daemon /usr/local/bin/colibri-daemon
|
||||
mdo -u root install -m 0555 target/release/colibri /usr/local/bin/colibri
|
||||
mdo -u root install -m 0555 target/release/colibri-smoke-agent /usr/local/bin/colibri-smoke-agent
|
||||
mdo -u root install -m 0555 target/release/colibri-mcp /usr/local/bin/colibri-mcp
|
||||
mdo -u root install -m 0555 target/release/colibri-tui /usr/local/bin/colibri-tui
|
||||
mdo -u root install -m 0555 packaging/freebsd/colibri_daemon.in /usr/local/etc/rc.d/colibri_daemon
|
||||
|
||||
mdo -u root chown -R colibri:colibri /var/run/colibri /var/db/colibri /var/log/colibri
|
||||
mdo -u root service colibri_daemon start
|
||||
```
|
||||
|
||||
`service colibri_daemon start` should return to the shell after a few seconds. If
|
||||
it stays in the foreground, check that the rc.d script uses
|
||||
`colibri_daemon_binary`, not `colibri_daemon_program`, and that `command=` is
|
||||
`/usr/sbin/daemon`.
|
||||
|
||||
## Validate runtime
|
||||
|
||||
```sh
|
||||
service colibri_daemon status
|
||||
colibri status
|
||||
colibri list-skills | head
|
||||
colibri-mcp tools
|
||||
```
|
||||
|
||||
Useful deeper checks:
|
||||
|
||||
```sh
|
||||
service colibri_daemon health
|
||||
tail -80 /var/log/colibri/daemon.log
|
||||
ls -l /var/run/colibri
|
||||
sockstat -u | grep colibri || true
|
||||
```
|
||||
|
||||
## Record what was installed
|
||||
|
||||
After a successful live rebuild, write a small local manifest:
|
||||
|
||||
```sh
|
||||
cd /home/clawdie/ai/colibri-build
|
||||
commit=$(git rev-parse HEAD)
|
||||
branch=$(git symbolic-ref --short -q HEAD || echo detached)
|
||||
now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
|
||||
|
||||
cat > /tmp/colibri-live-rebuild.json <<EOF
|
||||
{
|
||||
"repo": "https://code.smilepowered.org/clawdie/colibri.git",
|
||||
"branch": "${branch}",
|
||||
"commit": "${commit}",
|
||||
"installed_at": "${now}",
|
||||
"note": "Built and installed on running live USB"
|
||||
}
|
||||
EOF
|
||||
|
||||
mdo -u root install -m 0644 /tmp/colibri-live-rebuild.json /var/db/colibri/live-rebuild.json
|
||||
mdo -u root sha256 /usr/local/bin/colibri-daemon /usr/local/bin/colibri /usr/local/bin/colibri-mcp /usr/local/bin/colibri-tui \
|
||||
> /tmp/colibri-live-rebuild.sha256
|
||||
mdo -u root install -m 0644 /tmp/colibri-live-rebuild.sha256 /var/db/colibri/live-rebuild.sha256
|
||||
```
|
||||
|
||||
Report both files with validation notes when handing findings back through git.
|
||||
|
||||
## Fast rc.d-only repair
|
||||
|
||||
If only the service script is broken and no binary rebuild is needed, fetch the
|
||||
current Colibri rc.d source directly:
|
||||
|
||||
```sh
|
||||
mdo -u root fetch -o /usr/local/etc/rc.d/colibri_daemon \
|
||||
https://code.smilepowered.org/clawdie/colibri/raw/branch/main/packaging/freebsd/colibri_daemon.in
|
||||
mdo -u root chmod 555 /usr/local/etc/rc.d/colibri_daemon
|
||||
mdo -u root service colibri_daemon restart
|
||||
```
|
||||
|
||||
Sanity checks:
|
||||
|
||||
```sh
|
||||
grep -n 'colibri_daemon_program\|colibri_daemon_binary\|^command=\|^command_args=' /usr/local/etc/rc.d/colibri_daemon
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
- `colibri_daemon_binary` exists.
|
||||
- `command="/usr/sbin/daemon"` exists.
|
||||
- no `colibri_daemon_program` remains.
|
||||
- no `-u ${colibri_daemon_user}` remains in `command_args`.
|
||||
|
||||
## Future ISO improvement
|
||||
|
||||
Add a helper script, tentatively `/usr/local/bin/colibri-live-rebuild`, that
|
||||
automates this runbook:
|
||||
|
||||
1. clone/update `/home/clawdie/ai/colibri-build`
|
||||
2. checkout requested branch or commit
|
||||
3. run the release build
|
||||
4. stop `colibri_daemon`
|
||||
5. install binaries and rc.d script
|
||||
6. clean stale socket/pid files
|
||||
7. restart and validate `colibri status`
|
||||
8. write `/var/db/colibri/live-rebuild.json` and `.sha256`
|
||||
|
||||
This keeps the live USB usable as a self-hosted Colibri validation target while
|
||||
preserving ISO rebuilds for release artifacts.
|
||||
Loading…
Add table
Reference in a new issue