Improved installation guide (informalsystems#684)

* Fix for issue informalsystems#672 in the guide

* Apply suggestions from code review

Co-authored-by: Romain Ruetschi <romain@informal.systems>

* Simplified description. Added locked by default

* changelog

Co-authored-by: Romain Ruetschi <romain@informal.systems>

CHANGELOG.md

@@ -40,7 +40,7 @@
   - [nothing yet]
 
 - [ibc-relayer-cli]
-  - [nothing yet]
+  - Hermes guide: improved installation guideline ([#672])
 
 ### BREAKING CHANGES
 
@@ -53,6 +53,7 @@
 - [ibc-relayer-cli]
   - [nothing yet]
 
+[#672]: https://github.com/informalsystems/ibc-rs/issues/672
 [#599]: https://github.com/informalsystems/ibc-rs/issues/599
 [#685]: https://github.com/informalsystems/ibc-rs/issues/685
 [#689]: https://github.com/informalsystems/ibc-rs/issues/689
@@ -117,7 +118,6 @@ involving packet acks in a 3-chain setup. More details below.
 [#643]: https://github.com/informalsystems/ibc-rs/issues/643
 [#665]: https://github.com/informalsystems/ibc-rs/issues/665
 [#671]: https://github.com/informalsystems/ibc-rs/pull/671
-[#672]: https://github.com/informalsystems/ibc-rs/issues/672
 [#682]: https://github.com/informalsystems/ibc-rs/issues/682
 
 [ibc]: https://github.com/informalsystems/ibc-rs/tree/master/modules

guide/src/help.md

@@ -9,7 +9,7 @@ For this purpose, we recommend a few ideas that could be of help:
 - [patch][patching] your local gaia chain(s) to enable some corner-case methods
   (e.g., channel close);
 
-And if the above do not help:
+And if the above options do not address your specific problem:
 - you can [request a new feature][feature];
 - or consult the [list of reported issues][issues] and search by relevant
   keywords to see if you're dealing with a known problem;

guide/src/installation.md

@@ -1,16 +1,65 @@
 # Install the relayer
 
-In order to install and run Hermes, please follow the steps below:
+There are two main approaches for obtaining Hermes:
 
-> NOTE: This assumes you have installed all the [pre-requisites](./pre_requisites.md) on your machine.
+1. Installation:
+   1. If you are running on a Unix machine (Linux/MacOS), then the simplest
+      option is to [download the latest binary](#Install-by-downloading).
+   2. You can also install via [Cargo](#install-via-cargo).
+
+2. Alternatively, [build Hermes directly from source](#build-from-source).
+
+
+## Install by downloading
+
+Simply head to the GitHub [Releases][releases] page and download the latest
+version of Hermes binary matching your platform:
+- MacOS: `hermes-v0.1.1-x86_64-apple-darwin.tar.gz` (or .zip),
+- Linux: `hermes-v0.1.1-x86_64-unknown-linux-gnu.tar.gz` (or .zip).
+
+The step-by-step instruction below should carry you through the whole process:
+
+1. Make the directory where we'll place the binary:
+   ```shell
+   mkdir -p $HOME/.hermes/bin
+   ```
+
+2. Extract the binary archive:
+   ```shell
+   tar -C $HOME/.hermes/bin/ -vxzf $ARCHIVE_NAME
+   ```
+
+3. Update your path, by adding this line in your `.bashrc` or `.zshrc` shell
+   configuration file:
+   ```shell
+   export PATH="$HOME/.hermes/bin:$PATH"
+   ```
+
+> NOTE: The binary may be initially prevented from running if you're
+> on MacOS.
+> See the ["Open Anyway" instructions from this support forum][developer-app]
+> if that is the case.
+
+You should now be able to run Hermes by invoking the `hermes` executable.
+
+```shell
+hermes version
+```
+
+```
+hermes 0.1.1
+```
 
 ## Install via Cargo
 
+> NOTE: This approach assumes you have installed all
+> the [pre-requisites](./pre_requisites.md) on your machine.
+
 Hermes is packaged in the `ibc-relayer-cli` Rust crate.
 To install the latest release of Hermes, run the following command in a terminal:
 
 ```shell
-cargo install ibc-relayer-cli
+cargo install ibc-relayer-cli --bin hermes --locked
 ```
 
 This will download and build the crate `ibc-relayer-cli`, and install the 
@@ -75,6 +124,14 @@ If the build is successful, the `hermes` executable will be located in the follo
 ./target/release/hermes
 ```
 
+__Troubleshooting__:
+In case the `cargo build` command above fails, as a first course of action we
+recommend trying to run the same command with the additional `locked` flag:
+
+```shell
+cargo build --release --bin hermes --locked
+```
+
 ### Running for the first time
 
 If you run the `hermes` without any additional parameters you should see the usage and help information:
@@ -113,3 +170,7 @@ alias hermes='cargo run --release --bin hermes --'
 ### Next Steps
 
 Go to the [`Configuration`](./config.md) section to learn how to create a configuration file to be used by Hermes.
+
+
+[releases]: https://github.com/informalsystems/ibc-rs/releases
+[developer-app]: https://support.apple.com/en-gb/HT202491