Finalize README

docker/README.md

@@ -64,8 +64,16 @@ found on the github page of the project [here](https://github.com/libp2p/js-libp
 This is a provision system that compiles and deploys the contracts to any Ethereum blockchain.
 
 A Dockerfile is provided in the path `./docker/concordia-contracts` that will build the contracts used by Concordia and
-handle their deployment to any Ethereum network defined using env-vars upon container run. The image makes use of the
-environment variables described bellow.
+handle their deployment to any Ethereum network defined using env-vars upon container run. Dockerfile contains three
+useful stages, described in the table bellow.
+
+| Stage name | Entrypoint | Usage |
+| --- | --- | --- |
+| compile | Exits immediately | Compiles the contracts |
+| test | Runs contract tests | Compiles contracts and runs tests using blockchain defined by env vars |
+| runtime | Migrates contracts | Compiles contracts and migrates to the blockchain defined by env vars. Does **not** run tests |
+
+The image makes use of the environment variables described bellow.
 
 | Environment variable | Default value | Usage |
 | --- | --- | --- |
@@ -83,7 +91,15 @@ the image.
 ### Application
 
 The Dockerfile provided in the path `./docker/concordia-application` builds the application for production and serves
-the resulting build using an nginx server. The image makes use of the environment variables described bellow.
+the resulting build using an nginx server. Dockerfile contains two useful stages, described in the table bellow.
+
+| Stage name | Entrypoint | Usage |
+| --- | --- | --- |
+| test | Runs tests | Fetches npm packages and runs tests |
+| runtime | Serves application | Builds for production and serves it through nginx |
+
+
+The image makes use of the environment variables described bellow.
 
 | Environment variable | Default value | Usage |
 | --- | --- | --- |
@@ -91,7 +107,7 @@ the resulting build using an nginx server. The image makes use of the environmen
 | REACT_APP_RENDEZVOUS_PORT | 9090 | Set the port of the rendezvous server |
 
 **Attention**: this image will copy the contract artifacts from the directory `/packages/concordia-contracts/build`.
-The image is bound the these artifacts after build. If the contracts change or get re=deployed the image must be
+The image is bound the these artifacts after build. If the contracts change or get re-deployed the image must be
 re-built to use the new artifacts.
 
 **Attention**: make sure the contracts have been deployed before **building** this image. Also, make sure the rendezvous
@@ -109,14 +125,90 @@ These scripts are documented in the following chapters.
 
 ### <a name="piat-mkfile-targets"></a> Makefile targets
 
-Concordia uses blockchain and other distributed technologies. There are a number of ways to setup a running instance of
+Concordia uses blockchain and other distributed technologies. There are a number of ways to set up a running instance of
 this application.
 
-This chapter will guide you through a testing and a production setup that depend on local blockchain (ganache) instances
-which do not require real ETH to work or have any other charges.
+This chapter will guide you through simple setups for testing and production that depend on local blockchain (ganache)
+instances which do not require real ETH to work or have any other charges.
+
+#### Testing the contracts
+
+Build the ganache image and spin up a blockchain for testing:
+
+```shell
+make build-ganache run-ganache-test
+```
+
+Build the testing stage of the contracts image:
+
+```shell
+make build-contracts-tests
+```
+
+Run the tests:
+
+```shell
+make run-contract-tests
+```
+
+The results should be printed in the terminal, but are also available in the directory `./reports/contracts`.
+
+#### Testing the application
+
+Build the testing stage of the application image:
+
+```shell
+make build-app-tests
+```
+
+Run the test:
+
+```shell
+make run-app-tests
+```
+
+The results should be printed in the terminal, but are also available in the directory `./reports/app`.
+
+#### Production
+
+Build the ganache image and spin up a blockchain and a rendezvous server:
+
+```shell
+make run
+```
+
+Build the migration stage of the contracts image:
+
+```shell
+make build-contracts-migrate
+```
+
+Deploy the contracts to the blockchain:
+
+```shell
+make run-contracts-migrate
+```
+
+**Attention**: this step must be executed before building the application image (next step).
+
+Build the application image:
+
+```shell
+make build-app
+```
+
+Deploy the application:
+
+```shell
+make run-app
+```
+
+Head to [localhost:8473](localhost:8473) and voilà, a working Concordia instance appears! The blockchain is exposed in
+the address `localhost:8545`.
 
-TODO
+**Tip**: the accounts (private keys) generated by Ganache are available in the file `./volumes/ganache_keys/keys.json`.
 
 ### Env Files
 
-TODO
+Targets in the Makefile make use of env files suffixed by `.docker` located in the directory `./env`. Using this
+environment variables, you can change various configuration options of the testing/production deploys.