From 11cb281bd2619a3edcd568a1d4fcf4e978a32abc Mon Sep 17 00:00:00 2001 From: Apostolof Date: Wed, 2 Dec 2020 21:55:31 +0200 Subject: [PATCH] Finalize README --- docker/README.md | 110 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 101 insertions(+), 9 deletions(-) diff --git a/docker/README.md b/docker/README.md index 44dab71..af0d37a 100644 --- a/docker/README.md +++ b/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. ### 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.