chore: README updates, example updates (#352)

Fixes: #350 and
#348

Co-authored-by: Boris Mann <boris@bmannconsulting.com>

README.md

@@ -45,8 +45,6 @@
   </p>
 </div>
 
-<div align="center"><sub>:warning: Work in progress :warning:</sub></div>
-
 ##
 
 ## Outline
@@ -63,20 +61,24 @@
 ## Quickstart
 
 If you're looking to help develop `homestar`, please dive right into our
-[development](./DEVELOPMENT.md) guide. Otherwise, the easiest way
-to get started and see `homestar` in action is to follow-along and run our
-image-processing [websocket relay](./examples/websocket-relay) example,
-which integrates `homestar` with a browser application to run a
+[development](./DEVELOPMENT.md) guide.
+
+Otherwise, the easiest way to get started and "see" `homestar` in action is to
+follow-along and run our image-processing
+[websocket relay](./examples/websocket-relay) example, which integrates
+`homestar` with a browser application to run a
 statically-configured workflow. The associated `README.md` walks through
 what to install (i.e. `rust`, `node/npm`, `ipfs`), what commands
 to run, and embeds a video demonstrating its usage.
 
 Throughout the `homestar` ecosystem and documentation, we'll draw a distinction
 between the [host runtime][host-runtime] and the support for different
-[guest languages and bindings][guest]. If you're mainly interested in
-learning how to write and build-out Wasm components (in Rust), please jump
-into our [`homestar-functions`](./homestar-functions) directory
-and check out our examples there.
+[guest languages and bindings][guest].
+
+If you're mainly interested in learning how to write and build-out Wasm
+components (currently focused on authoring in Rust), please jump into
+our [`homestar-functions`](./homestar-functions) directory and check out
+our examples there.
 
 ## Running Examples
 
@@ -89,10 +91,10 @@ as a system.
 
 Our current list includes:
 
-- [websocket relay](./examples/websocket-relay) - An example (browser-based)
-  application that connects to the `homestar-runtime` over a websocket
-  connection in order to run a couple static Wasm-based, image processing
-  workflows that chain inputs and outputs.
+- [websocket relay](./examples/websocket-relay/README.md) - An example
+  (browser-based) application that connects to the `homestar-runtime` over a
+  websocket connection in order to run a couple static Wasm-based, image
+  processing workflows that chain inputs and outputs.
 
 ## Workspace
 

examples/websocket-relay/Cargo.toml

@@ -14,6 +14,7 @@ homestar-runtime = { path = "../../homestar-runtime", default-features = false,
 ] }
 miette = { version = "5.10", features = ["fancy"] }
 retry = "2.0"
+sysinfo = { version = "0.29", default-features = false }
 tracing = "0.1"
 
 [[bin]]

examples/websocket-relay/README.md

@@ -2,10 +2,12 @@
 
 ## Description
 
-An example application that connects to a **single** `homestar-runtime` node
+An example application that connects to a `homestar-runtime` node
 over a websocket connection in order to run static Wasm-based, image
 processing workflows that chain inputs and outputs using
-[inlined promises][pipelines]. This application demonstrates:
+[inlined promises][pipelines].
+
+This application demonstrates:
 
   * websocket notifications of [Ucan Invocation receipts][spec-receipts] sent
     between a web client and a `homestar` runner
@@ -26,9 +28,6 @@ To get started, please install:
 If you're using our [nix file](../../flake.nix)], you get these installs for
 free.
 
-*Note*: you **do not** have to start-up `kubo`/`ipfs` on your own. The example
-will do this for you.
-
 ## Usage
 
 1. Run `cargo run -- start -c config/settings.toml` to start the runtime and
@@ -44,12 +43,40 @@ will do this for you.
 
    https://www.loom.com/share/b0f882adc2ea45709d1f3031b5e61e92?sid=29cb403e-c666-4753-82f5-e35bbb710151
 
-Note that IPFS may attempt to upgrade to a new version and produce an error after the update. Delete the `tmp/.ipfs/` directory and restart to reset the IPFS repo state.
+Following along with the video, once you're up and running on `localhost`,
+you'll see two workflows with several tasks. You can click on the stack icon on
+the top right hand corner to inspect the source of the workflows.
+
+Running the first workflow completes a number of image-processing tasks, i.e.
+`crop` -> `rotate90` -> `blur`, submitting the rendered output to each
+subsequent task.
+
+The second workflow executes `crop` -> `rotate90` as well, and then something
+new: `grayscale`. As demonstrated, the first two task executions can be skipped
+if they've been previously run.
+
+## Tips & Common Issues
+
+- On macOS, for example, a simple homebrew install would install everything you
+need: `brew install rust npm ipfs`
+
+- Running `homestar` via `cargo run` requires a minimum Rust version of
+`1.70.0`. If you've got an older install of rust, update it with
+`rustup update`.
+
+You do not have to start-up `kubo`/`ipfs` on your own. The example will do this
+for you, and use `examples/websocket-relay/tmp/.ipfs` as a local blockstore.
+Feel free to discard it when you don't need it.
+
+If you're already running an IPFS instance however, e.g. [IPFS Desktop][ipfs-desktop],
+the example will check for an already running instance and not start a new,
+local one.
 
 [install-ipfs]: https://docs.ipfs.tech/install/
 [install-npm]: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
 [install-rust]: https://www.rust-lang.org/tools/install
 [ipfs]: https://ipfs.tech/
+[ipfs-desktop]: https://docs.ipfs.tech/install/ipfs-desktop/
 [ipld]: https://ipld.io/
 [pipelines]: https://github.com/ucan-wg/invocation#9-pipelines
 [rust-binary]: https://doc.rust-lang.org/book/ch01-03-hello-cargo.html#building-for-release