geth/docs/dogfood-checklist.md

Two-Machine Dogfood Checklist

This checklist is the pre-deployment evidence gate for using geth as a base layer for scripts, infrastructure automation, and other projects. Complete it 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.

Test Matrix

• [ ] Machine A platform, architecture, geth version/commit, and install method recorded.
• [ ] Machine B platform, architecture, geth version/commit, and install method recorded.
• [ ] Both machines use fresh GETH_HOME directories.
• [ ] Any skipped item has an explicit reason and follow-up issue.

Fresh Install And Owner Init

On Machine A:

geth init --admin-key ~/.ssh/id_ed25519.pub --signing-key ~/.ssh/id_ed25519 --node-name owner
geth daemon service install --start
geth wait daemon --timeout-ms 30000
geth status --json
geth doctor --json
geth peer export --out /tmp/owner.peer.json

Acceptance:

• [ ] User-level service starts without privileged service-manager mutation.
• [ ] geth wait daemon succeeds.
• [ ] geth status --json reports a node ID, agent ID, store status ok, and Iroh endpoint status.
• [ ] geth doctor --json is actionable and has no unexplained failures.
• [ ] The exported peer card contains the current owner node ID and endpoint.

Enrollment And Peer Exchange

Move /tmp/owner.peer.json to Machine B.

On Machine B:

geth init
geth peer import /tmp/owner.peer.json
geth node enroll request --node-name worker --out /tmp/worker-enrollment.json
geth node enroll submit owner --path /tmp/worker-enrollment.json

On Machine A:

geth node enroll list --status pending
geth node enroll approve <request-id> --signing-key ~/.ssh/id_ed25519
geth peer export --out /tmp/owner-approved.peer.json

On Machine B:

geth node enroll sync owner
geth keychain status --json
geth wait peer owner --timeout-ms 30000

Acceptance:

• [ ] Machine B imports Machine A as an untrusted peer candidate.
• [ ] Enrollment request submission reaches Machine A over Iroh.
• [ ] Machine A approval records signed keychain/auth operations.
• [ ] Machine B sync imports only valid signed operations.
• [ ] geth wait peer owner succeeds after enrollment.

Grants And Positive Sync Paths

On Machine A:

geth kv create prefs
geth document create notes
geth cas add README.md
geth pipe listen ops
geth auth grant <worker-node-id> resource:kv:prefs kv.read --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-kv-read
geth auth grant <worker-node-id> resource:document:notes document.read --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-document-read
geth auth grant <worker-node-id> resource:cas:local cas.fetch --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-cas-fetch
geth auth grant <worker-node-id> resource:pipe:ops pipe.connect --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-pipe-connect
geth auth grant <worker-node-id> resource:ssh-proxy:local ssh_proxy.connect --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-ssh-proxy

On Machine B:

geth auth sync owner
geth kv sync owner prefs
geth document sync owner notes
geth cas fetch owner <hash>
geth pipe send ops "dogfood" --node owner
geth ssh proxy owner
geth sync now owner
geth sync status --json

Acceptance:

• [ ] Auth sync imports the expected grants.
• [ ] KV sync imports prefs.
• [ ] Document sync imports notes.
• [ ] 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.
• [ ] geth sync status --json reports healthy or intentionally skipped streams with actionable next_action values.

Denied Remote Operations

On Machine B, attempt at least one operation without a matching grant:

geth kv sync owner missing-or-denied
geth pipe listen denied --node owner
geth ssh admin-shell owner status

Acceptance:

• [ ] Denied operations return stable JSON or text errors with recovery hints.
• [ ] Machine A state does not mutate after denied operations.
• [ ] Machine A logs include command/resource/capability fields without bearer tokens or private material.

Backup, Restore, Restart, And Doctor

On Machine A:

geth backup create --out /tmp/geth-backup
geth daemon service stop
geth daemon service start
geth wait daemon --timeout-ms 30000
geth doctor --json

On a separate validation home:

geth backup restore /tmp/geth-backup --target-home /tmp/geth-restore
GETH_HOME=/tmp/geth-restore geth doctor --json

Acceptance:

• [ ] Backup excludes private SSH admin keys.
• [ ] Restore writes to the validation home without mutating the original home.
• [ ] Service restart preserves identity, peer cards, resources, and sync cursors.
• [ ] Intentionally broken setups produce actionable geth doctor --json output.

Upgrade Evidence

For every tagged pre-release after the first:

geth --version
geth status --json
geth doctor --json

Acceptance:

• [ ] Previous tagged pre-release homes migrate forward.
• [ ] Store schema, config, keychain/auth logs, CAS metadata, and peer cards survive upgrade.
• [ ] Rollback expectations in docs/release-support-policy.md match the observed behavior.

Sign-Off

• [ ] All commands above match the current README and CLI help.
• [ ] Evidence is attached for Machine A.
• [ ] 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.