From eaeb7448bcc59fd73d21181bbfb2b6c911b87884 Mon Sep 17 00:00:00 2001 From: Apostolof Date: Tue, 1 Dec 2020 01:36:38 +0200 Subject: [PATCH] Add docker README chapters --- docker/README.md | 134 ++++++++++++++++++++++++----- docker/ganache/start-blockchain.sh | 2 +- 2 files changed, 113 insertions(+), 23 deletions(-) diff --git a/docker/README.md b/docker/README.md index c258cf6..b2d6d09 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,32 +1,122 @@ -# Concordia Docker Images +# Concordia Dockerized -## Dockerfiles provided +This README provides information about the provided docker images, their configuration and supported deployment +strategies. -Concordia uses blockchain and other distributed technologies. There are a number of ways to setup a running instance of -this application. +TLDR: head down to the [Putting it all together/Scripts](#piat-mkfile-targets) for a quick setup. + +## Services + +Concordia requires at the minimum two services to work, a blockchain and a rendezvous server. + +Additionally, the Concordia application code must be provided to the user. Currently, the only way of distributing the +application code is via a webserver as a web application. + +### Ganache + +Ganache is a personal blockchain software used during development. It is a very convenient way of developing and testing +dApps. More information can be found in the project's [website](https://www.trufflesuite.com/ganache). + +Note that any other Ethereum compliant blockchain can be used. + +### Rendezvous + +Concordia uses a distributed database to store forum data. A rendezvous server is needed in order for users to discover +peers in the network and get access to the network. + +### Application + +The Concordia application is a React app that handles interactions with the contracts and the distributed database used. + +## Docker images + +This repository provides docker images to easily setup (and destroy) instances of all required services Concordia. +Furthermore, we provide an image that builds the contracts and handles their migration to the blockchain in use. + +### Ganache + +The Dockerfile is provided in the path `./docker/ganache`. The image makes use of the environment variables described +bellow. + +| Environment variable | Default value | Usage | +| --- | --- | --- | +| ACCOUNTS_NUMBER | 10 | Set the number of accounts generated | +| ACCOUNTS_ETHER | 10 | Set the amount of ETH assigned to each account | +| MNEMONIC | myth like bonus scare over problem client lizard pioneer submit female collect | The mnemonic phrase sued as a seed for deterministic account generation | +| HOST | 0.0.0.0 | The hostname to listen on | +| PORT | 8545 | The port to listen on | +| NETWORK_ID | 5778 | The network id used to identify ganache | + +Note that the Ganache instance running inside the container will save the generated blockchain keys in the path +`/home/ganache_keys/keys.json`. If you need to access the keys (eg for getting a private key and importing in Metamask) +you can mount a volume to this path to have easier access. -This README will guide you through a testing setup that depends on a local blockchain (ganache) which does not require -real ETH to work or has any other charges. +Also, the database used by Ganache for storing blockchain information is placed in the path `/home/ganache_db/`. You can +maintain the blockchain state between runs by mounting a volume to the database path. -For this configuration the services needed are: +### Rendezvous -- A blockchain (ganache) -- A server that helps peers connect and route their messages to other (rendezvous) -- A service or provision system to compile and deploy the contracts to the blockchain (concordia-contracts image) -- An HTML server that provides access to the Concordia application (concordia-app image) +The rendezvous server used here is `js-libp2p-webrtc-star`. The server listens on port 9090. More information can be +found on the github page of the project [here](https://github.com/libp2p/js-libp2p-webrtc-star). -This repo provides Dockerfiles for all the above services. +### Contracts + +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. + +| Environment variable | Default value | Usage | +| --- | --- | --- | +| MIGRATE_NETWORK | develop | Set the network where the contracts will be deployed/tested (set to env unless you know what you're doing) | +| DEPLOY_CHAIN_HOST | NaN | Set the hostname of the blockchain network that will be used for deployment | +| DEPLOY_CHAIN_PORT | NaN | Set the port of the blockchain network that will be used for deployment | +| TEST_CHAIN_HOST | NaN | Set the hostname of the blockchain network that will be used for testing | +| TEST_CHAIN_PORT | NaN | Set the port of the blockchain network that will be used for testing | + +You can find the contract artifacts in the directory `/usr/src/concordia/packages/concordia-contracts/build/` inside +the image. + +**Attention**: make sure the targeted blockchain is up and running before trying to migrate the contracts. + +### 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. + +| Environment variable | Default value | Usage | +| --- | --- | --- | +| REACT_APP_RENDEZVOUS_HOST | 127.0.0.1 | Set the hostname of the rendezvous server | +| 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 (and hence the artifacts) change the image must be +re-built for the changes to take effect. + +**Attention**: make sure the contracts have been deployed before **building** this image. Also, make sure the rendezvous +server is up and running. + +## Docker Compose + +A docker-compose file also is provided. The docker-compose handles the lifecycle of the Ganache and Rendezvous server +containers. + +## Putting it all together + +You can find some ready to use scripts for common scenarios like dev deploys and testing in the `./docker` directory. +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 +this application. -## Concordia Contracts Image +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. -Makefile --> build contracts --> build migrate --> build tests --> get contracts out --> run tests --> run migrate +TODO -env files +### Env Files -## Concordia Application Image +TODO diff --git a/docker/ganache/start-blockchain.sh b/docker/ganache/start-blockchain.sh index 49dbaa7..6d3b4c9 100644 --- a/docker/ganache/start-blockchain.sh +++ b/docker/ganache/start-blockchain.sh @@ -1,7 +1,7 @@ #!/bin/sh N_ACCOUNTS="${ACCOUNTS_NUMBER:-10}" -ETHER="${ACCOUNTS_ETHER:-1000}" +ETHER="${ACCOUNTS_ETHER:-10}" MNEMONIC="${MNEMONIC:-"myth like bonus scare over problem client lizard pioneer submit female collect"}" HOST="${HOST:-"0.0.0.0"}" PORT="${PORT:-8545}"