[project] Update README with docker information (#2107)

* [project] Update README with docker information

* [docker] Add hmy bash completions to env

Dockerfile

@@ -70,3 +70,7 @@ RUN eval "$(~/bin/gimme ${GIMME_GO_VERSION})" ; scripts/install_build_tools.sh
 RUN eval "$(~/bin/gimme ${GIMME_GO_VERSION})" ; scripts/go_executable_build.sh
 
 RUN cd ${HMY_PATH}/go-sdk && make -j8 && cp hmy /root/bin
+
+RUN echo ". <(hmy completion)" >> /root/.profile
+
+RUN echo ". <(hmy completion)" >> /root/.bashrc

README.md

@@ -6,7 +6,119 @@
 [![Coverage Status](https://coveralls.io/repos/github/harmony-one/harmony/badge.svg?branch=master)](https://coveralls.io/github/harmony-one/harmony?branch=master)
 [![Go Report Card](https://goreportcard.com/badge/github.com/harmony-one/harmony)](https://goreportcard.com/report/github.com/harmony-one/harmony)
 
-## Installation Requirements
+# Play with the blockchain
+
+## Running the harmony blockchain with docker
+
+The easiest way to run our blockchain locally is to use docker.
+If you are on `OS X`, then install docker via `brew`.
+
+```
+$ brew cask install docker
+$ open /Applications/Docker.app
+```
+
+then you can run
+
+```
+$ docker run -it harmonyone/main:stable /bin/bash
+```
+
+You'll be in this current repository when the shell opens up, now let's catch up on any missing
+commits (all the following commands assume you are in the running docker container)
+
+### Bleeding edge master
+
+```
+$ git fetch
+$ git reset --hard origin/master
+```
+
+### Mainnet release intended branch
+
+```
+$ git fetch
+$ git checkout s3
+$ git reset --hard origin/s3
+```
+
+And now run the local blockchain
+
+```
+$ test/debug.sh
+```
+
+## Using our hmy command line tool
+
+Assuming that you got `test/debug.sh` running in your docker container, we can interact with
+the running blockchain using our `hmy` command line tool. Its part of our
+[go-sdk](https://github.com/harmony-one/go-sdk) repo, but our docker container already has it as
+well and built.
+
+Find your running container's ID, here's an example
+
+```
+$ docker container ls
+CONTAINER ID        IMAGE                    COMMAND             CREATED             STATUS              PORTS               NAMES
+62572a199bac        harmonyone/main:stable   "/bin/bash"         2 minutes ago       Up 2 minutes                            awesome_cohen
+```
+
+now lets get our second shell in the running container:
+
+```
+$ docker exec -it 62572a199bac /bin/bash
+```
+
+The container already comes with a prebuilt `hmy` that you can invoke anywhere, but lets go ahead
+and build the latest version.
+
+```
+$ cd ../go-sdk
+$ git fetch
+$ git reset --hard origin/master
+$ make
+$ ./hmy version
+Harmony (C) 2020. hmy, version v211-698b282 (@harmony.one 2020-01-17T00:58:51+0000)
+```
+
+Then checkout `./hmy cookbook` for example usages. The majority of commands output legal `JSON`,
+here is one example:
+
+```
+root@62572a199bac:~/go/src/github.com/harmony-one/go-sdk# ./hmy blockchain latest-header
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "blockHash": "0x34a8b155f90b8fc22342fc8b5d1c969ed836a2f666c506e4017b570dc337e88c",
+    "blockNumber": 0,
+    "epoch": 0,
+    "lastCommitBitmap": "",
+    "lastCommitSig": "000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+    "leader": "one1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqquzw7vz",
+    "shardID": 0,
+    "timestamp": "2019-06-28 15:00:00 +0000 UTC",
+    "unixtime": 1561734000,
+    "viewID": 0
+  }
+}
+```
+
+## Developing in the container
+
+The docker container is a full harmony development environment and comes with emacs, vim, ag, tig
+and other creature comforts. Most importantly, it already has the go environment with our C/C++
+based library dependencies (`libbls` and `mcl`) setup correctly for you. You can also change go
+versions easily, an example:
+
+```
+$ eval $(gimme 1.12.6)
+```
+
+Note that changing the go version might mean that dependencies won't work out right when trying to
+run `test/debug.sh` again, get the correct environment again easily by `exec bash`.
+
+## Installation Requirements for directly on your machine
 
 GMP and OpenSSL
 
@@ -36,7 +148,7 @@ make
 
 ```
 
-Note: make sure to run ``` scripts/install_build_tools.sh ```to make sure build tools are of correct versions.
+Note: make sure to run `scripts/install_build_tools.sh`to make sure build tools are of correct versions.
 
 ## Build
 
@@ -50,6 +162,7 @@ export LIBRARY_PATH=$LD_LIBRARY_PATH
 export DYLD_FALLBACK_LIBRARY_PATH=$LD_LIBRARY_PATH
 export GO111MODULE=on
 ```
+
 Note : Some of our scripts require bash 4.x support, please [install bash 4.x](http://tldrdevnotes.com/bash-upgrade-3-4-macos) on MacOS X.
 
 ### Build all executables
@@ -92,6 +205,7 @@ The script starts 2 shards and 7 nodes in each shard.
 ```
 
 ### Test local blockchain
+
 ```bash
 source scripts/setup_bls_build_flags.sh
 ./bin/wallet list
@@ -99,6 +213,7 @@ source scripts/setup_bls_build_flags.sh
 ```
 
 ### Terminate the local blockchain
+
 ```bash
 ./test/kill_nodes.sh
 ```