From 0595b3953294d98a60ad3a55aeaaad51cb40683b Mon Sep 17 00:00:00 2001 From: Eric Wendland Date: Sat, 11 Jul 2026 11:54:50 +0200 Subject: [PATCH] docs: tighten deployment runbooks --- README.md | 44 +++++++++++++++++- docs/dogfood-checklist.md | 69 ++++++++++++++++++++++++++-- docs/production-readiness-roadmap.md | 10 ++++ docs/roadmap.md | 18 +++++--- 4 files changed, 128 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 12bfe30..000a2ee 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,48 @@ documents, blobs, pipes, and future multi-user collaboration. This project is not the Ethereum `geth` client. The project and executable are still named `geth`. +## First 10 Minutes + +Build the single binary, initialize an isolated home, start the daemon, and +verify the local control path: + +```sh +cargo build -p geth +export GETH_HOME="$(mktemp -d)" +printf 'GETH_HOME=%s\n' "$GETH_HOME" +./target/debug/geth init +./target/debug/geth daemon run +``` + +Keep the daemon running. In a second shell, reuse the printed `GETH_HOME` value: + +```sh +export GETH_HOME="" +./target/debug/geth wait daemon --timeout-ms 30000 +./target/debug/geth status --json +./target/debug/geth doctor --json +``` + +This creates a local-only identity for evaluation. Before enrolling other +machines, use the owner setup in `geth guide owner-setup`; it records an +OpenSSH admin public key as the trust anchor and signs the initial keychain +statements without copying the private key into geth state. + +Start with these documents when moving beyond the local smoke test: + +- [`docs/architecture.md`](docs/architecture.md): ownership, trust, transport, + and module boundaries. +- [`docs/command-stability.md`](docs/command-stability.md): commands suitable + for automation and commands that remain experimental. +- [`docs/compatibility.md`](docs/compatibility.md): CLI, JSON, protocol, store, + and signed-operation compatibility rules. +- [`docs/automation-examples.md`](docs/automation-examples.md): shell, Python, + and user-service examples. +- [`docs/production-readiness-roadmap.md`](docs/production-readiness-roadmap.md): + the pre-deployment gate and its current status. +- [`docs/dogfood-checklist.md`](docs/dogfood-checklist.md): required + two-machine evidence before broader deployment. + ## One Binary There is one executable: `geth`. @@ -85,7 +127,7 @@ a binary OpenSSH KRL generated through `ssh-keygen -k`. `geth ssh cert sync `geth ssh revocation sync ` pull certificate-flow and revocation metadata from an authorized peer over Iroh. -## MVP Features +## Current Feature Surface The bootstrap implementation provides: diff --git a/docs/dogfood-checklist.md b/docs/dogfood-checklist.md index 13223c4..df3bc90 100644 --- a/docs/dogfood-checklist.md +++ b/docs/dogfood-checklist.md @@ -6,6 +6,34 @@ on two real machines before the first broader deployment. Do not mark the Phase 10 roadmap item complete until every checkbox here has a date, platform, geth version or commit, and evidence note. +Create one evidence directory per run and keep raw JSON, command transcripts, +and relevant redacted logs there. Do not store bearer tokens, private keys, or +unencrypted backup contents in the evidence directory. A run is reviewable only +when its evidence can be tied to the matrix and sign-off records below. + +## Evidence Log + +Copy this table for each attempt. Use ISO 8601 timestamps and paths or issue +links that another reviewer can open. + +| Field | Machine A | Machine B | +| --- | --- | --- | +| Run ID | `` | `` | +| Started at | `` | `` | +| Platform/architecture | `` | `` | +| geth version/commit | `` | `` | +| Install method/artifact checksum | `` | `` | +| Fresh `GETH_HOME` | `` | `` | +| Command transcript | `` | `` | +| JSON and log evidence | `` | `` | +| Result | `pass` / `fail` / `incomplete` | `pass` / `fail` / `incomplete` | + +Record each failed or skipped step separately: + +| Timestamp | Machine | Step | Result | Evidence | Follow-up | +| --- | --- | --- | --- | --- | --- | +| `` | `A` / `B` | `
` | `` | `` | `` | + ## Test Matrix - `[ ]` Machine A platform, architecture, geth version/commit, and install @@ -80,7 +108,9 @@ On Machine A: ```sh geth kv create prefs +geth kv set prefs theme dark geth document create notes +geth document set notes '{"purpose":"dogfood"}' geth cas add README.md geth pipe listen ops geth auth grant resource:kv:prefs kv.read --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-kv-read @@ -95,22 +125,45 @@ On Machine B: ```sh geth auth sync owner geth kv sync owner prefs +geth kv get prefs theme geth document sync owner notes +geth document get notes geth cas fetch owner geth pipe send ops "dogfood" --node owner -geth ssh proxy owner geth sync now owner geth sync status --json ``` +Back on Machine A, verify the pipe payload: + +```sh +geth pipe recv ops +``` + +Verify the SSH proxy with a bounded OpenSSH probe from Machine B. Replace +`` with an account accepted by Machine A's local SSH service: + +```sh +ssh -o BatchMode=yes -o ConnectTimeout=10 \ + -o 'ProxyCommand=geth ssh proxy owner' \ + @owner true +``` + +An authentication failure after the SSH handshake is sufficient to prove byte +transport when Machine A intentionally has no matching SSH credential; record +the verbose `ssh -v` transcript. A timeout or geth authorization error is not a +successful proxy check. + Acceptance: - `[ ]` Auth sync imports the expected grants. -- `[ ]` KV sync imports `prefs`. -- `[ ]` Document sync imports `notes`. +- `[ ]` KV sync imports `prefs` and Machine B reads `theme=dark`. +- `[ ]` Document sync imports the `{"purpose":"dogfood"}` state. - `[ ]` CAS fetch retrieves the expected blob. -- `[ ]` Pipe send reaches the Machine A daemon-lifetime listener. -- `[ ]` SSH proxy opens only after `ssh_proxy.connect` is granted. +- `[ ]` Pipe send reaches the Machine A listener and `pipe recv` returns the + exact payload. +- `[ ]` The bounded SSH probe reaches Machine A's SSH handshake only after + `ssh_proxy.connect` is granted. - `[ ]` `geth sync status --json` reports healthy or intentionally skipped streams with actionable `next_action` values. @@ -186,3 +239,9 @@ Acceptance: - `[ ]` Evidence is attached for Machine B. - `[ ]` Phase 10 in `docs/production-readiness-roadmap.md` is marked complete only after the real-machine evidence is reviewed. + +| Role | Name | Timestamp | Run ID | Result | +| --- | --- | --- | --- | --- | +| Operator A | `` | `` | `` | `` | +| Operator B | `` | `` | `` | `` | +| Reviewer | `` | `` | `` | `approved` / `rejected` | diff --git a/docs/production-readiness-roadmap.md b/docs/production-readiness-roadmap.md index 65e4605..08a9e42 100644 --- a/docs/production-readiness-roadmap.md +++ b/docs/production-readiness-roadmap.md @@ -41,6 +41,8 @@ behavior. endpoint ownership live outside the main feature handler module. - `[x]` Iroh accept-loop and background live-sync task spawning live outside the main feature handler module. + - `[x]` Graceful shutdown cancels daemon tasks, closes the shared Iroh + endpoint explicitly, and removes the local control socket. - `[x]` Runtime state is represented by narrow structs with documented ownership and locking rules. - `[x]` Existing daemon startup and status tests pass unchanged. @@ -334,6 +336,14 @@ platform/version details, and evidence for this gate. This phase cannot be marked complete from local unit or integration tests alone; it requires two real machines and tagged pre-release upgrade evidence. +- `[x]` Prepare the dogfood runbook and evidence format. + Acceptance criteria: + - `[x]` Runbook commands are checked against the current CLI command tree. + - `[x]` Positive paths verify transferred data, not only command exit status. + - `[x]` Streaming checks are bounded or have explicit completion criteria. + - `[x]` Evidence records capture platform, artifact, version, timestamp, + result, and follow-up details without collecting private material. + - `[ ]` Complete two-machine dogfood checklist. Acceptance criteria: - `[ ]` Fresh install works on at least two real machines. diff --git a/docs/roadmap.md b/docs/roadmap.md index 03e7da7..952c76b 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,7 +1,10 @@ # Roadmap -This roadmap is intended to be checkable. Each item should either be completed -with tests/docs or split into smaller items before implementation. +This is the long-term product and feature roadmap. It is intentionally broader +than the pre-deployment hardening effort, so unchecked items here do not imply +that a completed production-readiness phase has regressed. Each item should +either be completed with tests/docs or split into smaller items before +implementation. Status markers: @@ -93,10 +96,11 @@ admin devices without depending on one always-online coordination server. equivalent to Keyhive/BeeKEM, WireGuard, NetBird, or Tailscale unless those properties are actually implemented and tested. -## Prototype Viability Closure Plan +## Initial Viability Closure Plan -These are the remaining gaps that must close before the prototype is a smooth -end-to-end test target for the intended personal mesh use cases. +These items established a smooth end-to-end test target for the intended +personal mesh use cases. The cross-cutting pre-deployment requirements and the +remaining real-machine gate are tracked in the production-readiness roadmap. Implementation order: @@ -168,7 +172,7 @@ Implementation order: - `[x]` Tests assert conflicting replicated keychain/auth records do not mutate local trust or resource state. -- `[~]` Remote authorization enforcement audit. +- `[x]` Remote authorization enforcement audit. Acceptance criteria: - `[x]` Every remote mutable operation has an explicit resource capability check before mutating local state or opening a host service, or is @@ -176,7 +180,7 @@ Implementation order: - `[x]` A test-backed remote guard matrix documents the expected guard for each remote operation and fails if mutating/service-opening operations rely on discovery alone. - - `[ ]` Tests cover denied and allowed paths for CAS, KV, DB, document, + - `[x]` Tests cover denied and allowed paths for CAS, KV, DB, document, pubsub, pipe, SSH proxy/admin shell, SSH cert metadata, and revocations. - `[x]` Initial two-daemon denied-mutation coverage exists for remote pubsub publish, remote pipe listen, and SSH admin shell.