56 lines
2.8 KiB
Markdown
56 lines
2.8 KiB
Markdown
# Terminal UAT deployment runbook
|
|
|
|
Status: prepared, 2026-10-09. This runbook targets the physical Framework node
|
|
(`framework-pt`) and does not authorize an OTA, catalog publication, or wallet
|
|
mutation.
|
|
|
|
## Candidate contents
|
|
|
|
Build and record the backend binary, dashboard bundle, and source commit from
|
|
the isolated terminal worktree. The backend must have `ARCHY_SESSION_STATE_DIR`
|
|
set to the developer account's shared state directory (or use the default
|
|
resolution in `api/handler/terminal.rs`). Preserve the existing web root and
|
|
service binary before any replacement.
|
|
|
|
## Preconditions
|
|
|
|
1. Verify the Framework hostname and SSH host key through the operator's
|
|
approved connection mechanism. A plain `ssh framework-pt` must not be used
|
|
until host-key verification is available.
|
|
2. Capture service/container state, boot ID, running binary digest, served UI
|
|
digest, and the existing `/var/lib/archipelago/support` layout without
|
|
printing credentials, wallet files, or environment contents.
|
|
3. Create a timestamped protected rollback directory under
|
|
`/var/lib/archipelago/support/terminal-uat-<timestamp>`.
|
|
|
|
## Acceptance flow
|
|
|
|
- Open the dashboard as the node owner; unauthenticated requests to
|
|
`/api/terminal/sessions` and `/ws/terminal` return 401.
|
|
- Create a named session, type `printf 'uat\n'`, close the terminal, reopen it,
|
|
and resume the same session without a duplicate tmux process.
|
|
- Refresh the browser and reconnect after a temporary network interruption.
|
|
- Verify the terminal panel stays bounded while output grows, keeps an inner
|
|
scroll position at the newest line, and supports drag, resize, minimize,
|
|
refresh, and fullscreen controls without blocking dashboard navigation.
|
|
- Open a second owner browser and verify inventory visibility; verify only one
|
|
active attachment sends input at a time before enabling transfer controls.
|
|
- Confirm explicit End stops the tmux process but preserves the workspace.
|
|
- Reboot acceptance is separate: processes may stop, metadata must remain, and
|
|
the UI must call this interrupted rather than a live resume.
|
|
- Verify the Omarchy-derived agent skill files and app starter are present in
|
|
the candidate source/artifact; do not treat a local npm install failure as a
|
|
successful app build.
|
|
|
|
The node's reverse proxy must route `/api/terminal/` to the Archipelago daemon
|
|
(`127.0.0.1:5678`) in both HTTP and HTTPS server blocks. `/ws` already carries
|
|
the terminal WebSocket upgrade. Without the REST location, the SPA fallback
|
|
returns `index.html` instead of the authenticated session response.
|
|
|
|
## Rollback
|
|
|
|
Stop exposing the new dashboard before restoring the previous UI/backend pair.
|
|
Restore only from the protected receipt, verify the previous hashes and health,
|
|
and leave terminal session metadata/workspaces untouched unless the operator
|
|
explicitly requests session cleanup.
|