Improved installation guide

CHANGELOG.md

@@ -1,64 +1,65 @@
 # Changelog
 
-[comment]: <> (## Unreleased Changes)
+## Unreleased Changes
 
-[comment]: <> (> [high level summary])
+> [high level summary]
 
-[comment]: <> (### FEATURES)
+### FEATURES
 
-[comment]: <> (- [ibc])
+- [ibc]
 
-[comment]: <> (  - [nothing yet])
+  - [nothing yet]
 
-[comment]: <> (- [ibc-relayer])
+- [ibc-relayer]
 
-[comment]: <> (  - [nothing yet])
+  - [nothing yet]
 
-[comment]: <> (- [ibc-relayer-cli])
+- [ibc-relayer-cli]
 
-[comment]: <> (  - [nothing yet])
+  - [nothing yet]
 
-[comment]: <> (### IMPROVEMENTS)
+### IMPROVEMENTS
 
-[comment]: <> (- [ibc])
+- [ibc]
 
-[comment]: <> (  - [nothing yet])
+  - [nothing yet]
 
-[comment]: <> (- [ibc-relayer])
+- [ibc-relayer]
 
-[comment]: <> (  - [nothing yet])
+  - [nothing yet]
 
-[comment]: <> (- [ibc-relayer-cli])
+- [ibc-relayer-cli]
 
-[comment]: <> (  - [nothing yet])
+  - [nothing yet]
 
-[comment]: <> (### BUG FIXES)
+### BUG FIXES
 
-[comment]: <> (- [ibc])
+- [ibc]
 
-[comment]: <> (  - [nothing yet])
+  - [nothing yet]
 
-[comment]: <> (- [ibc-relayer])
+- [ibc-relayer]
 
-[comment]: <> (  - [nothing yet])
+  - [nothing yet]
 
-[comment]: <> (- [ibc-relayer-cli])
+- [ibc-relayer-cli]
+  - Hermes guide: improved installation guideline ([#672]) 
 
-[comment]: <> (  - [nothing yet])
+### BREAKING CHANGES
 
-[comment]: <> (### BREAKING CHANGES)
+- [ibc]
 
-[comment]: <> (- [ibc])
+  - [nothing yet]
 
-[comment]: <> (  - [nothing yet])
+- [ibc-relayer]
 
-[comment]: <> (- [ibc-relayer])
+  - [nothing yet]
 
-[comment]: <> (  - [nothing yet])
+- [ibc-relayer-cli]
 
-[comment]: <> (- [ibc-relayer-cli])
+  - [nothing yet]
 
-[comment]: <> (  - [nothing yet])
+[#672]: https://github.com/informalsystems/ibc-rs/issues/672
 
 ## v0.1.1
 *February 17, 2021*
@@ -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
 
 ## v0.1.0

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,69 @@
 # 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. Alternatively, install via
+      [Cargo installation instructions](#install-via-cargo). 
+
+[comment]: <> (   Regardless of approach you choose, also follow the post-installation)
+
+[comment]: <> (   instructions therein.)
+
+2. Alternatively, [build Hermes directly from source](#build-from-source).
+
+
+## Install by downloading
+
+Simply head to the GitHub [Releases][releases] page download the latest version
+of Hermes binary matching your platform:
+- `hermes-v0.1.1-x86_64-apple-darwin.tar.gz` (or .zip) for MacOS,  
+- `hermes-v0.1.1-x86_64-unknown-linux-gnu.tar.gz` (or .zip) for Linux.
+
+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 $HOME/.hermes/
+   ```
+
+2. Extract the binary archive:
+   ```shell
+   tar -C $HOME/.hermes/ -vxzf $ARCHIVE_NAME
+   ```
+
+3. Update your path:
+   ```shell
+   export PATH="$HOME/.hermes:$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 assume 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
 ```
 
 This will download and build the crate `ibc-relayer-cli`, and install the 
@@ -35,6 +88,15 @@ hermes version
 hermes 0.1.1
 ```
 
+
+__Troubleshooting__:
+In case the `cargo install` command above fails, as a first course of action we
+recommend trying to run the same command with the additional `locked` flag:
+
+```shell
+cargo install ibc-relayer-cli --bin hermes --locked
+```
+
 ## Build from source
 
 ### Clone the repository
@@ -75,6 +137,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 +183,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