docs: added docker instructions to the exercises

README.md

@@ -56,13 +56,33 @@ For the purpose of our first example, we'll create a local channel within one pr
 [later examples](./documentation/guides/rust#readme), you'll see that it's just as easy to create
 end-to-end protected channels over multi-hop, multi-protocol transport routes:
 
-1. Install Rust
+1. Deploy Container
+
+    To reduce friction and focus the attention on learning, we recommend the usage of a Docker container for the learning exercise. To learn how to get started with Docker, please visit the [Get Started With Docker](https://docs.docker.com/get-docker/) documentation. Alternatively, you can skip to step 2 if you want to proceed with a non-containerized install.
+
+
+    This command may take a few minutes the first time you invoke it:
+
+    ```
+    docker run --rm -it -e HOST_USER_ID=$(id -u) --name ockam-learn ghcr.io/build-trust/ockam-builder:latest bash
+    ```
+    Upon completion, you will be placed inside the `/work` folder of the container. Next, add a text editior for editing files.
+
+    ```
+    apt update && apt install nano
+    ```
+
+    Go ahead and proceed to step 3.
+
+1. Install Rust (Optional)
+
+    **NOTE**: If you do not want to use a container for the learning excercise then you will need to install Rust locally. If you don't have it, please [install](https://www.rust-lang.org/tools/install) the latest version of Rust. Only do this step if you chose to not use the learning container.
 
     ```
     curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
     ```
 
-2. Setup a new cargo project to get started.
+1. Setup a new cargo project to get started.
 
     ```
     cargo new --lib hello_ockam && cd hello_ockam && mkdir examples &&
@@ -73,7 +93,13 @@ end-to-end protected channels over multi-hop, multi-protocol transport routes:
     [post a question](https://github.com/build-trust/ockam/discussions/1642),
     we would love to help.
 
-3. Create a file at `examples/hello.rs` and copy the below code snippet to it.
+1. Create a file at `examples/hello.rs`.
+
+    ```
+    nano examples/hello.rs
+    ```
+
+1. Copy the below code snippet into the `hello.rs`.
 
 ```rust
 // examples/hello.rs
@@ -130,6 +156,8 @@ async fn main(mut ctx: Context) -> Result<()> {
 
 ```
 
+You may exit and save the file by pressing the keys `Ctrl + X`
+
 4. Run the example
 
     ```
@@ -143,6 +171,8 @@ entities, established a mutually authenticated channel and then routed a message
 This involved running cryptographic protocols for generating keys, authenticating as an entity, performing
 an authenticated key exchange and exchanging messages with authenticated encryption.
 
+You may exit from the learning containers by pressing the following keys, `CTRL+C`, `CTRL+D` or type `exit` in the terminal.
+
 To learn more about how we make these powerful cryptographic protocols simple to use, please have a look
 at our [step-by-step guide](./documentation/guides/rust#readme) where we introduce the building blocks in Ockam.
 

documentation/guides/rust/README.md

@@ -24,7 +24,21 @@ Let's build mutually-authenticated, end-to-end protected communication between d
 
 ### Setup
 
-If you don't have it, please [install](https://www.rust-lang.org/tools/install) the latest version of Rust.
+To reduce friction and focus the attention on learning, we recommend the usage of a Docker container for the learning exercise. To learn how to get started with Docker, please visit the [Get Started With Docker](https://docs.docker.com/get-docker/) documentation.
+
+This command may take a few minutes the first time you invoke it:
+
+```
+docker run --rm -it -e HOST_USER_ID=$(id -u) --name ockam-learn  ghcr.io/build-trust/ockam-builder:latest bash
+```
+
+Upon completion, you will be placed inside the `/work` folder of the container. Next, add a text editior for editing files.
+
+```
+apt update && apt install nano
+```
+
+**NOTE**: If you do not want to use a container for the learning excercise then you will need to install Rust locally. If you don't have it, please [install](https://www.rust-lang.org/tools/install) the latest version of Rust. Only do this step if you chose to not use the learning container.
 
 ```
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
@@ -37,6 +51,12 @@ cargo new --lib hello_ockam && cd hello_ockam && mkdir examples &&
   echo 'ockam = "*"' >> Cargo.toml && cargo build
 ```
 
+You will need a total of three terminal windows and sessions with the learning container. Go ahead and create all three sessions now using the following command.
+
+```
+docker exec --workdir /work/hello_ockam -it ockam-learn bash
+```
+
 If the above instructions don't work on your machine, please
 [post a question](https://github.com/build-trust/ockam/discussions/1642),
 we would love to help.
@@ -54,3 +74,7 @@ we would love to help.
 <div style="display: none; visibility: hidden;">
 <hr><b>Next:</b> <a href="./get-started/01-node#readme">01. Node</a>
 </div>
+
+### Clean-up
+
+You may exit from the learning containers by pressing the following keys, `CTRL+C`, `CTRL+D` or type `exit` in the terminal. You may also close the terminal windows.

documentation/guides/rust/get-started/01-node/README.md

@@ -26,7 +26,7 @@ For your new node, create a new file at `examples/01-node.rs` in
 your [hello_ockam](../../#setup) project:
 
 ```
-touch examples/01-node.rs
+nano examples/01-node.rs
 ```
 
 Add the following code to this file:
@@ -45,6 +45,8 @@ async fn main(mut ctx: Context) -> Result<()> {
 
 ```
 
+You may exit and save the file by pressing the keys `Ctrl + X`.
+
 Here we add the `#[ockam::node]` attribute to an `async` main function that
 receives the node execution context as a parameter and returns `ockam::Result`
 which helps make our error reporting better.

documentation/guides/rust/get-started/02-worker/README.md

@@ -36,7 +36,7 @@ directory so we can easily reuse the `Echoer` in other examples that we'll
 write later in this guide:
 
 ```
-touch src/echoer.rs
+nano src/echoer.rs
 ```
 
 Add the following code to this file:
@@ -73,7 +73,13 @@ with the address of the `Echoer`. We then take the body of the incoming
 message and echo it back on its return route (more about routes soon).
 
 To make this Echoer type accessible to our main program, export it
-from `src/lib.rs` file by adding the following to it:
+from `src/lib.rs` file.
+
+```
+nano src/lib.rs
+```
+
+Add the following snipped to the `src/lib.rs` file:
 
 ```rust
 // src/mod
@@ -95,7 +101,7 @@ reply back from the `"echoer"`.
 Create a new file at:
 
 ```
-touch examples/02-worker.rs
+nano examples/02-worker.rs
 ```
 
 Add the following code to this file:

documentation/guides/rust/get-started/03-routing/README.md

@@ -31,7 +31,7 @@ Just before forwarding the message, `Hop`'s handle message function will:
 Create a new file at:
 
 ```
-touch src/hop.rs
+nano src/hop.rs
 ```
 
 Add the following code to this file:
@@ -71,7 +71,13 @@ impl Worker for Hop {
 ```
 
 To make this `Hop` type accessible to our main program, export it
-from `src/lib.rs` by adding the following to it:
+from `src/lib.rs`.
+
+```
+nano src/lib.rs
+```
+
+Add the following code snippet to it:
 
 ```rust
 mod hop;
@@ -95,7 +101,7 @@ route by passing `route!["h1", "echoer"]` to `send(..)`.
 Create a new file at:
 
 ```
-touch examples/03-routing.rs
+nano examples/03-routing.rs
 ```
 
 Add the following code to this file:
@@ -151,7 +157,7 @@ the `"echoer"` and route our message through them.
 Create a new file at:
 
 ```
-touch examples/03-routing-many-hops.rs
+nano examples/03-routing-many-hops.rs
 ```
 
 Add the following code to this file:
@@ -197,6 +203,9 @@ Note the message flow.
 
 <img src="./sequence-many-hops.png" width="100%">
 
+
+Go ahead and stop the program by pressing the keys `Ctrl + C`
+
 <div style="display: none; visibility: hidden;">
 <hr><b>Next:</b> <a href="../04-transport#readme">04. Transport</a>
 </div>

documentation/guides/rust/get-started/04-transport/README.md

@@ -18,7 +18,7 @@ a [responder](#responder-node) and an [initiator](#initiator-node).
 Create a new file at:
 
 ```
-touch examples/04-routing-over-transport-responder.rs
+nano examples/04-routing-over-transport-responder.rs
 ```
 
 Add the following code to this file:
@@ -55,7 +55,7 @@ async fn main(ctx: Context) -> Result<()> {
 Create a new file at:
 
 ```
-touch examples/04-routing-over-transport-initiator.rs
+nano examples/04-routing-over-transport-initiator.rs
 ```
 
 Add the following code to this file:
@@ -95,7 +95,7 @@ Run the responder:
 cargo run --example 04-routing-over-transport-responder
 ```
 
-Run the initiator:
+In a seperate window, run the initiator:
 
 ```
 cargo run --example 04-routing-over-transport-initiator
@@ -106,14 +106,16 @@ Note the message flow.
 <img src="./sequence.png" width="100%">
 
 
+Go ahead and stop each of the programs by pressing the keys `Ctrl + C`
+
 ## Routing over two transport hops
 
 ### Responder node
 
 Create a new file at:
 
 ```
-touch examples/04-routing-over-transport-two-hops-responder.rs
+nano examples/04-routing-over-transport-two-hops-responder.rs
 ```
 
 Add the following code to this file:
@@ -150,7 +152,7 @@ async fn main(ctx: Context) -> Result<()> {
 Create a new file at:
 
 ```
-touch examples/04-routing-over-transport-two-hops-middle.rs
+nano examples/04-routing-over-transport-two-hops-middle.rs
 ```
 
 Add the following code to this file:
@@ -184,7 +186,7 @@ async fn main(ctx: Context) -> Result<()> {
 Create a new file at:
 
 ```
-touch examples/04-routing-over-transport-two-hops-initiator.rs
+nano examples/04-routing-over-transport-two-hops-initiator.rs
 ```
 
 Add the following code to this file:
@@ -223,6 +225,8 @@ async fn main(mut ctx: Context) -> Result<()> {
 
 ## Run
 
+Each of the following commands must be run in one of the three terminal window sessions you opened up earlier.
+
 Run the responder:
 
 ```

documentation/guides/rust/get-started/05-secure-channel/README.md

@@ -27,7 +27,7 @@ maintaining a secure channel behind two simple functions:
 Create a new file at:
 
 ```
-touch examples/05-secure-channel-over-two-transport-hops-responder.rs
+nano examples/05-secure-channel-over-two-transport-hops-responder.rs
 ```
 
 Add the following code to this file:
@@ -77,7 +77,7 @@ async fn main(ctx: Context) -> Result<()> {
 Create a new file at:
 
 ```
-touch examples/05-secure-channel-over-two-transport-hops-middle.rs
+nano examples/05-secure-channel-over-two-transport-hops-middle.rs
 ```
 
 Add the following code to this file:
@@ -110,7 +110,7 @@ async fn main(ctx: Context) -> Result<()> {
 Create a new file at:
 
 ```
-touch examples/05-secure-channel-over-two-transport-hops-initiator.rs
+nano examples/05-secure-channel-over-two-transport-hops-initiator.rs
 ```
 
 Add the following code to this file:
@@ -157,6 +157,8 @@ async fn main(mut ctx: Context) -> Result<()> {
 
 ## Run
 
+Each of the following commands must be run in one of the three terminal window sessions you opened up earlier.
+
 Run the responder:
 
 ```

documentation/guides/rust/get-started/09-streams/README.md

@@ -113,7 +113,7 @@ Since both nodes know the stream names in advance, we don't need any additional
 Create a new file at:
 
 ```
-touch examples/09-streams-responder.rs
+nano examples/09-streams-responder.rs
 ```
 
 Add the following code to this file:
@@ -159,7 +159,7 @@ This code creates a stream client on the Hub node at `127.0.0.1:4000` and starts
 Create a new file at:
 
 ```
-touch examples/09-streams-initiator.rs
+nano examples/09-streams-initiator.rs
 ```
 
 Add the following code to this file:

documentation/guides/rust/get-started/10-secure-channel-via-streams/README.md

@@ -35,7 +35,7 @@ Encryption is managed by the nodes and ensures that Ockam Hub is unable to inspe
 Create a new file at:
 
 ```
-touch examples/10-secure-channel-via-streams-responder.rs
+nano examples/10-secure-channel-via-streams-responder.rs
 ```
 
 Add the following code to this file:
@@ -85,7 +85,7 @@ async fn main(ctx: Context) -> Result<()> {
 Create a new file at:
 
 ```
-touch examples/10-secure-channel-via-streams-initiator.rs
+nano examples/10-secure-channel-via-streams-initiator.rs
 ```
 
 Add the following code to this file:

documentation/guides/rust/get-started/README.md

@@ -28,7 +28,21 @@ Let's build mutually-authenticated, end-to-end protected communication between d
 
 ### Setup
 
-If you don't have it, please [install](https://www.rust-lang.org/tools/install) the latest version of Rust.
+To reduce friction and focus the attention on learning, we recommend the usage of a Docker container for the learning exercise. To learn how to get started with Docker, please visit the [Get Started With Docker](https://docs.docker.com/get-docker/) documentation.
+
+This command may take a few minutes the first time you invoke it:
+
+```
+docker run --rm -it -e HOST_USER_ID=$(id -u) --name ockam-learn  ghcr.io/build-trust/ockam-builder:latest bash
+```
+
+Upon completion, you will be placed inside the `/work` folder of the container. Next, add a text editior for editing files.
+
+```
+apt update && apt install nano
+```
+
+**NOTE**: If you do not want to use a container for the learning excercise then you will need to install Rust locally. If you don't have it, please [install](https://www.rust-lang.org/tools/install) the latest version of Rust. Only do this step if you chose to not use the learning container.
 
 ```
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
@@ -41,6 +55,12 @@ cargo new --lib hello_ockam && cd hello_ockam && mkdir examples &&
   echo 'ockam = "*"' >> Cargo.toml && cargo build
 ```
 
+You will need a total of three terminal windows and sessions with the learning container. Go ahead and create all three sessions now using the following command.
+
+```
+docker exec --workdir /work/hello_ockam -it ockam-learn bash
+```
+
 If the above instructions don't work on your machine, please
 [post a question](https://github.com/build-trust/ockam/discussions/1642),
 we would love to help.