mirror of https://github.com/poanetwork/quorum.git
Restructure and reorder Getting Started docs (#777)
* Create new page for installation instructions, add quorum cloud details * Break up QuorumExamples docs & move above CreatingFromScratch in sidebar
This commit is contained in:
chris-j-h
Samer Falah
parent
60eaf20d40
commit
9c0195fd57
|
|
@ -0,0 +1,247 @@
|
|||
# Setting up the 7nodes example
|
||||
|
||||
## Installation
|
||||
Clone the [`quorum-examples`](https://github.com/jpmorganchase/quorum-examples.git) repo.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/jpmorganchase/quorum-examples.git
|
||||
```
|
||||
|
||||
!!! Warning
|
||||
Any account/encryption keys used in the quorum-examples repo are for demonstration and testing purposes only. Before running a real environment, new keys should be generated using Geth's `account` tool, Tessera's `-keygen` option, and Constellation's `--generate-keys` option
|
||||
|
||||
## Prepare your environment
|
||||
|
||||
A 7 node Quorum network must be running before the example can be run. The [`quorum-examples`](https://github.com/jpmorganchase/quorum-examples.git) repo provides the means to create a pre-configured sample network in minutes.
|
||||
|
||||
There are 3 ways to start the sample network, each method is detailed below:
|
||||
|
||||
1. By running a pre-configured Vagrant virtual-machine environment which comes complete with Quorum, Constellation, Tessera and the 7nodes example already installed. Bash scripts provided in the examples are used to create the sample network.
|
||||
1. By running [`docker-compose`](https://docs.docker.com/compose/) against a [preconfigured `compose` file](https://github.com/jpmorganchase/quorum-examples/blob/master/docker-compose.yml) to create the sample network
|
||||
1. By installing Quorum and Tessera/Constellation locally and using bash scripts provided in the examples to create the sample network
|
||||
|
||||
Your environment must be prepared differently depending on the method being used to run the example.
|
||||
|
||||
### Running with Vagrant
|
||||
1. Install [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
|
||||
2. Install [Vagrant](https://www.vagrantup.com/downloads.html)
|
||||
3. Download and start the Vagrant instance (note: running `vagrant up` takes approx 5 mins):
|
||||
|
||||
```sh
|
||||
git clone https://github.com/jpmorganchase/quorum-examples
|
||||
cd quorum-examples
|
||||
vagrant up
|
||||
vagrant ssh
|
||||
```
|
||||
|
||||
4. To shutdown the Vagrant instance, run `vagrant suspend`. To delete it, run
|
||||
`vagrant destroy`. To start from scratch, run `vagrant up` after destroying the
|
||||
instance.
|
||||
|
||||
#### Troubleshooting Vagrant
|
||||
* If you are behind a proxy server, please see https://github.com/jpmorganchase/quorum/issues/23.
|
||||
* If you are using macOS and get an error saying that the ubuntu/xenial64 image doesn't
|
||||
exist, please run `sudo rm -r /opt/vagrant/embedded/bin/curl`. This is usually due to
|
||||
issues with the version of curl bundled with Vagrant.
|
||||
* If you receive the error `default: cp: cannot open '/path/to/geth.ipc' for reading: Operation not supported` after running `vagrant up`, run `./raft-init.sh` within the 7nodes directory on your local machine. This will remove temporary files created after running 7nodes locally and will enable `vagrant up` to execute correctly.
|
||||
|
||||
#### Troubleshooting Vagrant: Memory usage
|
||||
* The Vagrant instance is allocated 6 GB of memory. This is defined in the `Vagrantfile`, `v.memory = 6144`. This has been deemed a suitable value to allow the VM and examples to run as expected. The memory allocation can be changed by updating this value and running `vagrant reload` to apply the change.
|
||||
|
||||
* If the machine you are using has less than 8 GB memory you will likely encounter system issues such as slow down and unresponsiveness when starting the Vagrant instance as your machine will not have the capacity to run the VM. There are several steps that can be taken to overcome this:
|
||||
1. Shutdown any running processes that are not required
|
||||
1. If running the [7nodes example](../7Nodes), reduce the number of nodes started up. See the [7nodes: Reducing the number of nodes](../7Nodes#reducing-the-number-of-nodes) for info on how to do this.
|
||||
1. Set up and run the examples locally. Running locally reduces the load on your memory compared to running in Vagrant.
|
||||
|
||||
### Running with Docker
|
||||
|
||||
1. Install Docker (https://www.docker.com/get-started)
|
||||
- If your Docker distribution does not contain `docker-compose`, follow [this](https://docs.docker.com/compose/install/) to install Docker Compose
|
||||
- Make sure your Docker daemon has at least 4G memory
|
||||
- Required Docker Engine 18.02.0+ and Docker Compose 1.21+
|
||||
1. Download and run `docker-compose`
|
||||
```sh
|
||||
git clone https://github.com/jpmorganchase/quorum-examples
|
||||
cd quorum-examples
|
||||
docker-compose up -d
|
||||
```
|
||||
1. By default, the Quorum network is created with Tessera privacy managers and Istanbul BFT consensus. To use Raft consensus, set the environment variable `QUORUM_CONSENSUS=raft` before running `docker-compose`
|
||||
```sh
|
||||
QUORUM_CONSENSUS=raft docker-compose up -d
|
||||
```
|
||||
1. Run `docker ps` to verify that all quorum-examples containers (7 nodes and 7 tx managers) are **healthy**
|
||||
1. Run `docker logs <container-name> -f` to view the logs for a particular container
|
||||
1. __Note__: to run the 7nodes demo, use the following snippet to open `geth` Javascript console to a desired node (using container name from `docker ps`) and send a private transaction
|
||||
```sh
|
||||
$ docker exec -it quorum-examples_node1_1 geth attach /qdata/dd/geth.ipc
|
||||
Welcome to the Geth JavaScript console!
|
||||
|
||||
instance: Geth/node1-istanbul/v1.7.2-stable/linux-amd64/go1.9.7
|
||||
coinbase: 0xd8dba507e85f116b1f7e231ca8525fc9008a6966
|
||||
at block: 70 (Thu, 18 Oct 2018 14:49:47 UTC)
|
||||
datadir: /qdata/dd
|
||||
modules: admin:1.0 debug:1.0 eth:1.0 istanbul:1.0 miner:1.0 net:1.0 personal:1.0 rpc:1.0 txpool:1.0 web3:1.0
|
||||
|
||||
> loadScript('/examples/private-contract.js')
|
||||
```
|
||||
1. Shutdown Quorum Network
|
||||
```sh
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
#### Troubleshooting Docker
|
||||
|
||||
1. Docker is frozen
|
||||
- Check if your Docker daemon is allocated enough memory (minimum 4G)
|
||||
1. Tessera crashes due to missing file/directory
|
||||
- This is due to the location of `quorum-examples` folder is not shared
|
||||
- Please refer to Docker documentation for more details:
|
||||
- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/troubleshoot/#shared-drives)
|
||||
- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/#file-sharing)
|
||||
- [Docker Machine](https://docs.docker.com/machine/overview/): this depends on what Docker machine provider is used. Please refer to its documentation on how to configure shared folders/drives
|
||||
1. If you run Docker inside Docker, make sure to run the container with `--privileged`
|
||||
|
||||
### Running locally
|
||||
|
||||
!!! info
|
||||
Quorum must be run on Ubuntu-based/macOS machines. Constellation can only be run on Ubuntu-based machines. Running the examples therefore requires an Ubuntu-based/macOS machine. If running the examples using Constellation then an Ubuntu-based machine is required.
|
||||
|
||||
1. Install [Golang](https://golang.org/dl/)
|
||||
2. Download and build [Quorum](https://github.com/jpmorganchase/quorum/):
|
||||
|
||||
```sh
|
||||
git clone https://github.com/jpmorganchase/quorum
|
||||
cd quorum
|
||||
make
|
||||
GETHDIR=`pwd`; export PATH=$GETHDIR/build/bin:$PATH
|
||||
cd ..
|
||||
```
|
||||
|
||||
3. Download and build Tessera (see [README](https://github.com/jpmorganchase/tessera) for build options)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/jpmorganchase/tessera.git
|
||||
cd tessera
|
||||
mvn install
|
||||
```
|
||||
|
||||
4. Download quorum-examples
|
||||
```sh
|
||||
git clone https://github.com/jpmorganchase/quorum-examples
|
||||
```
|
||||
|
||||
## Starting the 7nodes sample network
|
||||
|
||||
!!! info
|
||||
This is not required if `docker-compose` has been used to prepare the network as the `docker-compose` command performs these actions for you
|
||||
|
||||
Shell scripts are included in the examples to make it simple to configure the network and start submitting transactions.
|
||||
|
||||
All logs and temporary data are written to the `qdata` folder.
|
||||
|
||||
The sample network can be created to run using Istanbul BFT, Raft or Clique POA consensus mechanisms. In the following commands replace `{consensus}` with one of `raft`, `istanbul` or `clique` depending on the consensus mechanism you want to use.
|
||||
|
||||
1. Navigate to the 7nodes example directory, configure the Quorum nodes and initialize accounts & keystores:
|
||||
```sh
|
||||
cd path/to/7nodes
|
||||
./{consensus}-init.sh
|
||||
```
|
||||
1. Start the Quorum and privacy manager nodes (Constellation or Tessera):
|
||||
- If running in Vagrant:
|
||||
```sh
|
||||
./{consensus}-start.sh
|
||||
```
|
||||
By default, Tessera will be used as the privacy manager. To use Constellation run the following:
|
||||
```
|
||||
./{consensus}-start.sh constellation
|
||||
```
|
||||
|
||||
- If running locally:
|
||||
```
|
||||
./{consensus}-start.sh tessera --tesseraOptions "--tesseraJar /path/to/tessera-app.jar"
|
||||
```
|
||||
|
||||
By default, `{consensus}-start.sh` will look in `/home/vagrant/tessera/tessera-app/target/tessera-app-{version}-app.jar` for the Tessera jar. `--tesseraOptions` must be provided so that the start script looks in the correct location for the Tessera jar:
|
||||
|
||||
Alternatively, the Tessera jar location can be specified by setting the environment variable `TESSERA_JAR`.
|
||||
|
||||
1. You are now ready to start sending private/public transactions between the nodes
|
||||
|
||||
1. To stop the network:
|
||||
```bash
|
||||
./stop.sh
|
||||
```
|
||||
|
||||
## Running the example
|
||||
`quorum-examples` includes some simple transaction contracts to demonstrate the privacy features of Quorum. See the [7nodes Example](../7Nodes) page for details on how to run them.
|
||||
|
||||
## Variations
|
||||
### Reducing the number of nodes
|
||||
It is easy to reduce the number of nodes used in the example network. You may want to do this for memory usage reasons or just to experiment with a different network configuration.
|
||||
|
||||
For example, to run the example with 5 nodes instead of 7, the following changes need to be made:
|
||||
|
||||
1. Reduce number of nodes being started
|
||||
1. In `{consensus}-start.sh`:
|
||||
|
||||
Comment out the following lines used to start Quorum nodes 6 & 7
|
||||
```sh
|
||||
# PRIVATE_CONFIG=qdata/c6/tm.ipc nohup geth --datadir qdata/dd6 $ARGS --raftport 50406 --rpcport 22005 --port 21005 --unlock 0 --password passwords.txt 2>>qdata/logs/6.log &
|
||||
# PRIVATE_CONFIG=qdata/c7/tm.ipc nohup geth --datadir qdata/dd7 $ARGS --raftport 50407 --rpcport 22006 --port 21006 --unlock 0 --password passwords.txt 2>>qdata/logs/7.log &
|
||||
```
|
||||
|
||||
1. In `constellation-start.sh` or `tessera-start.sh` (depending on which privacy manager you are using):
|
||||
|
||||
Change the 2 instances of `for i in {1..7}` to `for i in {1..5}`
|
||||
|
||||
1. `private-contract.js` by default sends a transaction to node 7. As node 7 will no longer be started this must be updated to instead send to node 5:
|
||||
|
||||
1. Copy node 5's public key from `./keys/tm5.pub`
|
||||
|
||||
2. Replace the existing `privateFor` in `private-contract.js` with the key copied from `tm5.pub` key, e.g.:
|
||||
``` javascript
|
||||
var simple = simpleContract.new(42, {from:web3.eth.accounts[0], data: bytecode, gas: 0x47b760, privateFor: ["R56gy4dn24YOjwyesTczYa8m5xhP6hF2uTMCju/1xkY="]}, function(e, contract) {...}
|
||||
```
|
||||
|
||||
1. Update the list of nodes involved in consensus
|
||||
* If using Raft
|
||||
1. Remove node 6 and node 7's enode addresses from `permissioned-nodes.json` (i.e. the entries with `raftport` `50406` and `50407`)
|
||||
* If using IBFT
|
||||
1. Find the 20-byte address representations of node 6 and node 7's nodekey (nodekeys located at `qdata/dd{i}/geth/nodekey`). There are many ways to do this, one is to run a script making use of `ethereumjs-wallet`:
|
||||
```node
|
||||
const wlt = require('ethereumjs-wallet');
|
||||
|
||||
var nodekey = '1be3b50b31734be48452c29d714941ba165ef0cbf3ccea8ca16c45e3d8d45fb0';
|
||||
var wallet = wlt.fromPrivateKey(Buffer.from(nodekey, 'hex'));
|
||||
|
||||
console.log('addr: ' + wallet.getAddressString());
|
||||
```
|
||||
1. Use `istanbul-tools` to decode the `extraData` field in `istanbul-genesis.json`
|
||||
```bash
|
||||
git clone https://github.com/jpmorganchase/istanbul-tools.git
|
||||
cd istanbul-tools
|
||||
make
|
||||
./build/bin/istanbul extra decode --extradata <...>
|
||||
```
|
||||
1. Copy the output into a new `.toml` file and update the formatting to the following:
|
||||
```yaml
|
||||
vanity = "0x0000000000000000000000000000000000000000000000000000000000000000"
|
||||
validators = [
|
||||
"0xd8dba507e85f116b1f7e231ca8525fc9008a6966",
|
||||
"0x6571d97f340c8495b661a823f2c2145ca47d63c2",
|
||||
...
|
||||
]
|
||||
```
|
||||
1. Remove the addresses of node 6 and node 7 from the validators list
|
||||
1. Use `istanbul-tools` to encode the `.toml` as `extraData`
|
||||
```bash
|
||||
./build/bin/istanbul extra encode --config /path/to/conf.toml
|
||||
```
|
||||
1. Update the `extraData` field in `istanbul-genesis.json` with output from the encoding
|
||||
|
||||
After making these changes, the `{consensus}-init.sh`, `{consensus}-start.sh`, and `./runscript.sh private-contract.js` scripts can be run as normal. You can then follow steps described above to verify that node 5 can see the transaction payload and that nodes 2-4 are unable to see the payload.
|
||||
|
||||
### Using a Tessera remote enclave
|
||||
Tessera v0.9 introduced the ability to run the privacy manager's enclave as a separate process from the Transaction Manager. This is a more secure way of being able to manage and interact with your keys.
|
||||
|
||||
To start a sample 7nodes network that uses remote enclaves run `./{consensus}-start.sh tessera-remote`. By default this will start 7 Transaction Managers, the first 4 of which use a remote enclave. If you wish to change this number, you will need to add the extra parameter `--remoteEnclaves X` in the `--tesseraOptions`, e.g. `./{consensus}-start.sh tessera-remote --tesseraOptions "--remoteEnclaves 7"`.
|
||||
|
|
@ -1,4 +1,7 @@
|
|||
# 7nodes
|
||||
# 7nodes Example
|
||||
## Set Up
|
||||
Start the 7nodes sample network by following the instructions in [7nodes Set Up](../7Nodes-Setup).
|
||||
|
||||
## Demonstrating Privacy
|
||||
The [7nodes example](https://github.com/jpmorganchase/quorum-examples/tree/master/examples/7nodes) comes with some simple contracts to demonstrate the privacy features of Quorum.
|
||||
|
||||
|
|
@ -13,7 +16,7 @@ In this demo we will:
|
|||
|
||||
### Sending a private transaction
|
||||
|
||||
First start running the 7nodes example by following the instructions in the [quorum-examples](../Quorum-Examples#getting-started), then send an example private contract from Node 1 to Node 7 (this is denoted by the public key passed via `privateFor: ["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="]` in `private-contract.js`):
|
||||
Send an example private contract from Node 1 to Node 7 (this is denoted by the Node 7's public key passed via `privateFor: ["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="]` in `private-contract.js`):
|
||||
``` bash
|
||||
./runscript.sh private-contract.js
|
||||
```
|
||||
|
|
@ -21,11 +24,10 @@ Make note of the `TransactionHash` printed to the terminal.
|
|||
|
||||
### Inspecting the Quorum nodes
|
||||
|
||||
We can inspect any of the Quorum nodes by using `geth attach` to open the Geth JavaScript console. For this demo, we will be inspecting Node 1, Node 7 and Node 4.
|
||||
We can inspect any of the Quorum nodes by using `geth attach` to open the Geth JavaScript console. For this demo, we will be inspecting Node 1, Node 4 and Node 7.
|
||||
|
||||
It is recommended to use separate terminal windows for each node we are inspecting. In each terminal, ensure you are in the `path/to/7nodes` directory, then:
|
||||
|
||||
- If you aren't already running the 7nodes example, in terminal 1 run `./{consensus}-init.sh` followed by `./{consensus}-start.sh`
|
||||
- In terminal 1 run `geth attach ipc:qdata/dd1/geth.ipc` to attach to node 1
|
||||
- In terminal 2 run `geth attach ipc:qdata/dd4/geth.ipc` to attach to node 4
|
||||
- In terminal 3 run `geth attach ipc:qdata/dd7/geth.ipc` to attach to node 7
|
||||
|
|
@ -75,21 +77,22 @@ Next we'll use ```eth.contract``` to define a contract class with the simpleStor
|
|||
```
|
||||
|
||||
The function calls are now available on the contract instance and you can call those methods on the contract. Let's start by examining the initial value of the contract to make sure that only nodes 1 and 7 can see the initialized value.
|
||||
|
||||
- In terminal window 1 (Node 1):
|
||||
``` javascript
|
||||
> private.get()
|
||||
42
|
||||
```
|
||||
``` javascript
|
||||
> private.get()
|
||||
42
|
||||
```
|
||||
- In terminal window 2 (Node 4):
|
||||
``` javascript
|
||||
> private.get()
|
||||
0
|
||||
```
|
||||
``` javascript
|
||||
> private.get()
|
||||
0
|
||||
```
|
||||
- In terminal window 3 (Node 7):
|
||||
``` javascript
|
||||
> private.get()
|
||||
42
|
||||
```
|
||||
``` javascript
|
||||
> private.get()
|
||||
42
|
||||
```
|
||||
|
||||
So we can see nodes 1 and 7 are able to read the state of the private contract and its initial value is 42. If you look in `private-contract.js` you will see that this was the value set when the contract was created. Node 4 is unable to read the state.
|
||||
|
||||
|
|
@ -103,22 +106,23 @@ In terminal window 1 (Node 1):
|
|||
"0xacf293b491cccd1b99d0cfb08464a68791cc7b5bc14a9b6e4ff44b46889a8f70"
|
||||
```
|
||||
You can check the log files in `7nodes/qdata/logs/` to see each node validating the block with this new private transaction. Once the block containing the transaction has been validated we can once again check the state from each node 1, 4, and 7.
|
||||
|
||||
- In terminal window 1 (Node 1):
|
||||
``` javascript
|
||||
> private.get()
|
||||
4
|
||||
```
|
||||
``` javascript
|
||||
> private.get()
|
||||
4
|
||||
```
|
||||
- In terminal window 2 (Node 4):
|
||||
``` javascript
|
||||
> private.get()
|
||||
0
|
||||
```
|
||||
``` javascript
|
||||
> private.get()
|
||||
0
|
||||
```
|
||||
- In terminal window 3 (Node 7):
|
||||
``` javascript
|
||||
> private.get()
|
||||
4
|
||||
```
|
||||
And there you have it. All 7 nodes are validating the same blockchain of transactions, the private transactions carrying only a 512 bit hash, and only the parties to private transactions are able to view and update the state of private contracts.
|
||||
``` javascript
|
||||
> private.get()
|
||||
4
|
||||
```
|
||||
And there you have it; all 7 nodes are validating the same blockchain of transactions, the private transactions carrying only a 512 bit hash on-chain, and only the parties to private transactions being able to view and update the state of private contracts.
|
||||
|
||||
## Permissions
|
||||
|
||||
|
|
@ -193,40 +197,5 @@ MISCELLANEOUS OPTIONS:
|
|||
## Next steps
|
||||
Additional samples can be found in `quorum-examples/examples/7nodes/samples` for you to use and edit. You can also create your own contracts to help you understand how the nodes in a Quorum network work together.
|
||||
|
||||
## Reducing the number of nodes
|
||||
It is easy to reduce the number of nodes used in the example. You may want to do this for memory usage reasons or just to experiment with a different network configuration.
|
||||
Take a look at [Creating a Network From Scratch](../Creating-A-Network-From-Scratch) for step-by-step instructions on how to create your own Quorum network.
|
||||
|
||||
To run the example with 5 nodes instead of 7, the following changes need to be made:
|
||||
1. In __`raft-start.sh`__:
|
||||
|
||||
Comment out the following lines used to start Quorum nodes 6 & 7
|
||||
```sh
|
||||
# PRIVATE_CONFIG=qdata/c6/tm.ipc nohup geth --datadir qdata/dd6 $ARGS --raftport 50406 --rpcport 22005 --port 21005 --unlock 0 --password passwords.txt 2>>qdata/logs/6.log &
|
||||
# PRIVATE_CONFIG=qdata/c7/tm.ipc nohup geth --datadir qdata/dd7 $ARGS --raftport 50407 --rpcport 22006 --port 21006 --unlock 0 --password passwords.txt 2>>qdata/logs/7.log &
|
||||
```
|
||||
|
||||
1. In __`constellation-start.sh`__ or __`tessera-start.sh`__ (depending on which privacy manager you are using):
|
||||
|
||||
Change the 2 instances of `for i in {1..7}` to `for i in {1..5}`
|
||||
|
||||
After making these changes, the `raft-init.sh` and `raft-start.sh` scripts can be run as normal.
|
||||
|
||||
`private-contract.js` will also need to be updated as this is set up to send a transaction from node 1 to node 7. To update the private contract to instead send to node 5, the following steps need to be followed:
|
||||
|
||||
1. Copy node 5's public key from `./keys/tm5.pub`
|
||||
|
||||
2. Replace the existing `privateFor` in `private-contract.js` with the key copied from `tm5.pub` key, e.g.:
|
||||
``` javascript
|
||||
var simple = simpleContract.new(42, {from:web3.eth.accounts[0], data: bytecode, gas: 0x47b760, privateFor: ["R56gy4dn24YOjwyesTczYa8m5xhP6hF2uTMCju/1xkY="]}, function(e, contract) {...}
|
||||
```
|
||||
|
||||
After saving this change, the `./runscript.sh private-contract.js` command can be run as usual to submit the private contract. You can then follow steps described above to verify that node 5 can see the transaction payload and that nodes 2-4 are unable to see the payload.
|
||||
|
||||
## Using a Tessera remote enclave
|
||||
Tessera v0.9 brought with it the option to have an enclave as a separate process from the Transaction
|
||||
Manager. This is a more secure way of being able to manage and interact with your keys.
|
||||
To use the remote enclave, call your desired start with using `tessera-remote` as the first
|
||||
parameter, e.g. `./raft-start.sh tessera-remote`. This will, by default, start 7 Transaction
|
||||
Managers, the first 4 of which use a remote enclave. If you wish to change this number, you
|
||||
will need to add the extra parameter `--remoteEnclaves X` in the `--tesseraOptions`, e.g.
|
||||
`./raft-start.sh tessera-remote --tesseraOptions "--remoteEnclaves 7"`.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Getting started from scratch
|
||||
# Creating a network from scratch
|
||||
|
||||
This section details easy to follow step by step instructions of how to setup one or more Quorum nodes from scratch for all new starters.
|
||||
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
# Getting Started Overview
|
||||
|
||||
This section details several ways to start using and working with Quorum, ranging from using a pre-configured sample network running in a virtual machine, to creating a full network from scratch.
|
||||
|
||||
## Quickstart with Quorum Examples' sample network
|
||||
|
||||
The easiest way to get a network up and running is by working through the [Quorum Examples](../Quorum-Examples). These examples provide the means to create a pre-configured sample Quorum network that can be started and be ready for use in minutes. The examples give the option of running the network either in a virtual-machine environment using Vagrant, in containers using docker-compose, or locally through the use of bash scripts to automate creation of the network.
|
||||
|
||||
## Creating a network from scratch
|
||||
|
||||
[Creating a Network From Scratch](../Creating-A-Network-From-Scratch) provides a step-by-step walkthrough of how to create and configure a Quorum network suitable for either Raft or Istanbul consensus. It also shows how to enable privacy and add/remove nodes as required.
|
||||
|
||||
## Creating a network deployed in the cloud
|
||||
|
||||
[Quorum Cloud](https://github.com/jpmorganchase/quorum-cloud) provides an example of how a Quorum network can be run on a cloud platform. It uses Terraform to create a 7 node Quorum network deployed on AWS using AWS ECS Fargate, S3 and an EC2.
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
# Installing
|
||||
|
||||
Quorum and its Privacy Managers can be installed and used as Docker containers, by building from source, or by downloading pre-built release binaries.
|
||||
|
||||
## As containers
|
||||
Docker containers exist for Quorum, Tessera and Constellation and can be found at the [`quorumengineering` Docker repository](https://hub.docker.com/u/quorumengineering/):
|
||||
|
||||
```
|
||||
docker pull quorumengineering/quorum
|
||||
docker pull quorumengineering/tessera
|
||||
docker pull quorumengineering/constellation
|
||||
```
|
||||
|
||||
## From source
|
||||
### Quorum
|
||||
|
||||
1. Clone the repository and build the source:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/jpmorganchase/quorum.git
|
||||
cd quorum
|
||||
make all
|
||||
```
|
||||
|
||||
Binaries are placed in `$REPO_ROOT/build/bin`. Add that folder to `PATH` to make `geth` and `bootnode` easily invokable, or copy those binaries to a folder already in `PATH`, e.g. `/usr/local/bin`.
|
||||
|
||||
An easy way to supplement `PATH` is to add `PATH=$PATH:/path/to/repository/build/bin` to your `~/.bashrc` or `~/.bash_aliases` file.
|
||||
|
||||
1. Run the tests:
|
||||
|
||||
```bash
|
||||
make test
|
||||
```
|
||||
|
||||
### Privacy Managers
|
||||
|
||||
#### Tessera
|
||||
Tessera is a production-ready implementation of Quorum's privacy manager. It is undergoing active development with new features being added regularly.
|
||||
|
||||
Follow the installation instructions on the [Tessera project page](https://github.com/jpmorganchase/tessera).
|
||||
|
||||
#### Constellation
|
||||
Constellation is the reference implementation of Quorum's privacy manager. It is still supported but no longer undergoing active development of new features.
|
||||
|
||||
Grab a package for your platform [here](https://github.com/jpmorganchase/constellation/releases), and place the extracted binaries somewhere in `PATH`, e.g. `/usr/local/bin`.
|
||||
|
||||
## As release binaries
|
||||
The pre-compiled release binaries for Quorum, Tessera and Constellation can be downloaded from the following links:
|
||||
|
||||
* [Quorum](https://github.com/jpmorganchase/quorum/releases)
|
||||
* [Tessera](https://github.com/jpmorganchase/tessera/releases)
|
||||
* [Constellation](https://github.com/jpmorganchase/constellation/releases)
|
||||
|
||||
Once downloaded, add the binaries to `PATH` to make them easily invokable.
|
||||
|
|
@ -1,181 +1,11 @@
|
|||
# Quorum Examples
|
||||
|
||||
This section details couple of setup [examples for Quorum](https://github.com/jpmorganchase/quorum-examples.git)
|
||||
The following examples can be used to demonstrate the functionality offered by Quorum as well as provide the means to easily create pre-configured networks for testing/development.
|
||||
|
||||
Current examples include:
|
||||
|
||||
* [7nodes](../7Nodes): Starts up a fully-functioning Quorum environment consisting of 7 independent nodes. From this example one can test consensus, privacy, and all the expected functionality of an Ethereum platform.
|
||||
* [5nodesRTGS](https://github.com/bacen/quorum-examples/tree/master/examples/5nodesRTGS): [__Note__: This links to an external repo which you will need to clone, thanks to @rsarres for this contribution!] Starts up a set of 5 nodes that simulates a Real-time Gross Setlement environment with 3 banks, one regulator (typically a central bank) and an observer that cannot access the private data.
|
||||
* [7nodes](https://github.com/jpmorganchase/quorum-examples.git): Starts up a fully-functioning Quorum environment consisting of 7 independent nodes. This example demonstrates consensus, privacy, and all the expected functionality of an Ethereum platform.
|
||||
* [5nodesRTGS](https://github.com/bacen/quorum-examples/tree/master/examples/5nodesRTGS): Starts up a set of 5 nodes that simulates a Real-time Gross Settlement environment with 3 banks, one regulator (typically a central bank) and an observer that cannot access the private data.
|
||||
|
||||
The easiest way to get started with running the examples is to use the vagrant environment (see below).
|
||||
|
||||
**Important note**: Any account/encryption keys contained in this repository are for
|
||||
demonstration and testing purposes only. Before running a real environment, you should
|
||||
generate new ones using Geth's `account` tool and the `--generate-keys` option for Constellation (or `-keygen` option for Tessera).
|
||||
|
||||
## Getting Started
|
||||
The 7nodes example can be run in three ways:
|
||||
|
||||
1. By running a preconfigured Vagrant environment which comes complete with Quorum, Constellation, Tessera and the 7nodes example (__works on any machine__).
|
||||
1. By running [`docker-compose`](https://docs.docker.com/compose/) against a preconfigured `compose` file ([example](https://github.com/jpmorganchase/quorum-examples/blob/master/docker-compose.yml) from the `quorum-examples` repo) which starts 7nodes example (tested on Windows 10, macOS Mojave & Ubuntu 18.04).
|
||||
1. By downloading and locally running Quorum, Tessera and the examples (__requires an Ubuntu-based/macOS machine; note that Constellation does not support running locally__)
|
||||
|
||||
### Setting up Vagrant
|
||||
1. Install [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
|
||||
2. Install [Vagrant](https://www.vagrantup.com/downloads.html)
|
||||
3. Download and start the Vagrant instance (note: running `vagrant up` takes approx 5 mins):
|
||||
|
||||
```sh
|
||||
git clone https://github.com/jpmorganchase/quorum-examples
|
||||
cd quorum-examples
|
||||
vagrant up
|
||||
vagrant ssh
|
||||
```
|
||||
|
||||
4. To shutdown the Vagrant instance, run `vagrant suspend`. To delete it, run
|
||||
`vagrant destroy`. To start from scratch, run `vagrant up` after destroying the
|
||||
instance.
|
||||
|
||||
#### Troubleshooting Vagrant
|
||||
* If you are behind a proxy server, please see https://github.com/jpmorganchase/quorum/issues/23.
|
||||
* If you are using macOS and get an error saying that the ubuntu/xenial64 image doesn't
|
||||
exist, please run `sudo rm -r /opt/vagrant/embedded/bin/curl`. This is usually due to
|
||||
issues with the version of curl bundled with Vagrant.
|
||||
* If you receive the error `default: cp: cannot open '/path/to/geth.ipc' for reading: Operation not supported` after running `vagrant up`, run `./raft-init.sh` within the 7nodes directory on your local machine. This will remove temporary files created after running 7nodes locally and will enable `vagrant up` to execute correctly.
|
||||
|
||||
#### Troubleshooting Vagrant: Memory usage
|
||||
* The Vagrant instance is allocated 6 GB of memory. This is defined in the `Vagrantfile`, `v.memory = 6144`. This has been deemed a suitable value to allow the VM and examples to run as expected. The memory allocation can be changed by updating this value and running `vagrant reload` to apply the change.
|
||||
|
||||
* If the machine you are using has less than 8 GB memory you will likely encounter system issues such as slow down and unresponsiveness when starting the Vagrant instance as your machine will not have the capacity to run the VM. There are several steps that can be taken to overcome this:
|
||||
1. Shutdown any running processes that are not required
|
||||
1. If running the [7nodes example](../7Nodes), reduce the number of nodes started up. See the [7nodes: Reducing the number of nodes](../7Nodes#reducing-the-number-of-nodes) for info on how to do this.
|
||||
1. Set up and run the examples locally. Running locally reduces the load on your memory compared to running in Vagrant.
|
||||
|
||||
### Setting up Docker
|
||||
|
||||
1. Install Docker (https://www.docker.com/get-started)
|
||||
- If your Docker distribution does not contain `docker-compose`, follow [this](https://docs.docker.com/compose/install/) to install Docker Compose
|
||||
- Make sure your Docker daemon has at least 4G memory
|
||||
- Required Docker Engine 18.02.0+ and Docker Compose 1.21+
|
||||
1. Download and run `docker-compose`
|
||||
```sh
|
||||
git clone https://github.com/jpmorganchase/quorum-examples
|
||||
cd quorum-examples
|
||||
docker-compose up -d
|
||||
```
|
||||
1. By default, Quorum Network is created using Tessera transaction manager and Istanbul BFT consensus. If you wish to change consensus configuration to Raft, set the environment variable `QUORUM_CONSENSUS=raft` before running `docker-compose`
|
||||
```sh
|
||||
QUORUM_CONSENSUS=raft docker-compose up -d
|
||||
```
|
||||
1. Run `docker ps` to verify that all quorum-examples containers (7 nodes and 7 tx managers) are **healthy**
|
||||
1. __Note__: to run the 7nodes demo, use the following snippet to open `geth` Javascript console to a desired node (using container name from `docker ps`) and send a private transaction
|
||||
```sh
|
||||
$ docker exec -it quorum-examples_node1_1 geth attach /qdata/dd/geth.ipc
|
||||
Welcome to the Geth JavaScript console!
|
||||
|
||||
instance: Geth/node1-istanbul/v1.7.2-stable/linux-amd64/go1.9.7
|
||||
coinbase: 0xd8dba507e85f116b1f7e231ca8525fc9008a6966
|
||||
at block: 70 (Thu, 18 Oct 2018 14:49:47 UTC)
|
||||
datadir: /qdata/dd
|
||||
modules: admin:1.0 debug:1.0 eth:1.0 istanbul:1.0 miner:1.0 net:1.0 personal:1.0 rpc:1.0 txpool:1.0 web3:1.0
|
||||
|
||||
> loadScript('/examples/private-contract.js')
|
||||
```
|
||||
1. Shutdown Quorum Network
|
||||
```sh
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
#### Troubleshooting Docker
|
||||
|
||||
1. Docker is frozen
|
||||
- Check if your Docker daemon is allocated enough memory (minimum 4G)
|
||||
1. Tessera is crashed due to missing file/directory
|
||||
- This is due to the location of `quorum-examples` folder is not shared
|
||||
- Please refer to Docker documentation for more details:
|
||||
- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/troubleshoot/#shared-drives)
|
||||
- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/#file-sharing)
|
||||
- [Docker Machine](https://docs.docker.com/machine/overview/): this depends on what Docker machine provider is used. Please refer to its documentation on how to configure shared folders/drives
|
||||
1. If you run Docker inside Docker, make sure to run the container with `--privileged`
|
||||
|
||||
### Setting up locally
|
||||
|
||||
!!! info
|
||||
This is only possible with Tessera. Constellation is not supported when running the examples locally. To use Constellation, the examples must be run in Vagrant.
|
||||
|
||||
1. Install [Golang](https://golang.org/dl/)
|
||||
2. Download and build [Quorum](https://github.com/jpmorganchase/quorum/):
|
||||
|
||||
```sh
|
||||
git clone https://github.com/jpmorganchase/quorum
|
||||
cd quorum
|
||||
make
|
||||
GETHDIR=`pwd`; export PATH=$GETHDIR/build/bin:$PATH
|
||||
cd ..
|
||||
```
|
||||
|
||||
3. Download and build Tessera (see [README](https://github.com/jpmorganchase/tessera) for build options)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/jpmorganchase/tessera.git
|
||||
cd tessera
|
||||
mvn install
|
||||
```
|
||||
|
||||
4. Download quorum-examples
|
||||
```sh
|
||||
git clone https://github.com/jpmorganchase/quorum-examples
|
||||
```
|
||||
|
||||
### Running the 7nodes example
|
||||
Shell scripts are included in the examples to make it simple to configure the network and start submitting transactions.
|
||||
|
||||
All logs and temporary data are written to the `qdata` folder.
|
||||
|
||||
#### Using Raft consensus
|
||||
|
||||
1. Navigate to the 7nodes example, configure the Quorum nodes and initialize accounts & keystores:
|
||||
```sh
|
||||
cd path/to/7nodes
|
||||
./raft-init.sh
|
||||
```
|
||||
2. Start the Quorum and privacy manager nodes (Constellation or Tessera):
|
||||
- If running in Vagrant:
|
||||
```sh
|
||||
./raft-start.sh
|
||||
```
|
||||
By default, Constellation will be used as the privacy manager. To use Tessera run the following:
|
||||
```
|
||||
./raft-start.sh tessera
|
||||
```
|
||||
By default, `raft-start.sh` will look in `/home/vagrant/tessera/tessera-app/target/tessera-app-{version}-app.jar` for the Tessera jar.
|
||||
|
||||
- If running locally with Tessera:
|
||||
```
|
||||
./raft-start.sh tessera --tesseraOptions "--tesseraJar /path/to/tessera-app.jar"
|
||||
```
|
||||
|
||||
The Tessera jar location can also be specified by setting the environment variable `TESSERA_JAR`.
|
||||
|
||||
3. You are now ready to start sending private/public transactions between the nodes
|
||||
|
||||
#### Using Istanbul BFT consensus
|
||||
To run the example using __Istanbul BFT__ consensus use the corresponding commands:
|
||||
```sh
|
||||
istanbul-init.sh
|
||||
istanbul-start.sh
|
||||
istanbul-start.sh tessera
|
||||
stop.sh
|
||||
```
|
||||
|
||||
#### Using Clique POA consensus
|
||||
To run the example using __Clique POA__ consensus use the corresponding commands:
|
||||
```sh
|
||||
clique-init.sh
|
||||
clique-start.sh
|
||||
clique-start.sh tessera
|
||||
stop.sh
|
||||
```
|
||||
|
||||
### Next steps: Sending transactions
|
||||
Some simple transaction contracts are included in quorum-examples to demonstrate the privacy features of Quorum. To learn how to use them see the [7nodes](../7Nodes).
|
||||
!!! Info
|
||||
The 5nodesRTGS example links to an external repo which you will need to clone, thanks to **@rsarres** for this contribution!
|
||||
|
|
|
|||
|
|
@ -1,39 +0,0 @@
|
|||
# Setup Overview & Quickstart
|
||||
|
||||
Using Quorum requires that a Quorum Node and a Constellation/Tessera Node are installed, configured and
|
||||
running (see build/installation instructions for both below). An overview of the steps to follow to manually set up Quorum, including key generation, genesis block & Constellation/Tessera configuration will be available soon, but for now the best way to get started is to use the pre-configured Vagrant environment that has been made available our Quorum Examples repo.
|
||||
|
||||
## Quickstart using Quorum Examples
|
||||
|
||||
The easiest way to get a network up and running is by following the steps in [Quorum Examples](../Quorum-Examples). This Vagrant environment automatically sets up a test Quorum network that is ready for development use within minutes and is the recommended approach if you are looking to get started with Quorum.
|
||||
|
||||
If you don't want to use the Quorum Examples approach and instead would like to manually set up Quorum then please see the instructions below (Note: this documentation is Work In Progress)
|
||||
|
||||
## Building Quorum Node From Source
|
||||
|
||||
Clone the repository and build the source:
|
||||
|
||||
```
|
||||
git clone https://github.com/jpmorganchase/quorum.git
|
||||
cd quorum
|
||||
make all
|
||||
```
|
||||
|
||||
Binaries are placed in `$REPO_ROOT/build/bin`. Put that folder in your PATH to make `geth` and `bootnode` easily invokable, or copy those binaries to a folder already in PATH, e.g. `/usr/local/bin`.
|
||||
|
||||
An easy way to supplement PATH is to add `PATH=$PATH:/path/to/repository/build/bin` to your `~/.bashrc` or `~/.bash_aliases` file.
|
||||
|
||||
Run the tests:
|
||||
|
||||
```
|
||||
make test
|
||||
```
|
||||
|
||||
## Installing Constellation
|
||||
Grab a package for your platform [here](https://github.com/jpmorganchase/constellation/releases), and place the extracted binaries somewhere in PATH, e.g. /usr/local/bin.
|
||||
|
||||
## Installing Tessera
|
||||
Follow the installation instructions on the [Tessera project page](https://github.com/jpmorganchase/tessera).
|
||||
|
||||
## Getting Started from Scratch
|
||||
Follow the instructions given [here](../Getting-Started-From-Scratch).
|
||||
14
mkdocs.yml
14
mkdocs.yml
|
|
@ -12,11 +12,13 @@ repo_url: https://github.com/jpmorganchase/quorum
|
|||
|
||||
nav:
|
||||
- Getting Started:
|
||||
- Setup Overview & Quickstart: Getting Started/Setup Overview & Quickstart.md
|
||||
- Getting Started From Scratch: Getting Started/Getting-Started-From-Scratch.md
|
||||
- Overview: Getting Started/Getting Started Overview.md
|
||||
- Installing: Getting Started/Installing.md
|
||||
- Quorum Examples:
|
||||
- Overview: Getting Started/Quorum-Examples.md
|
||||
- 7 Nodes Example: Getting Started/7Nodes.md
|
||||
- Overview: Getting Started/Quorum-Examples.md
|
||||
- 7nodes Set Up: Getting Started/7Nodes-Setup.md
|
||||
- 7nodes Example: Getting Started/7Nodes.md
|
||||
- Creating a Network From Scratch: Getting Started/Creating-A-Network-From-Scratch.md
|
||||
- Running Quorum: Getting Started/running.md
|
||||
- Quorum API: Getting Started/api.md
|
||||
- Consensus:
|
||||
|
|
@ -28,7 +30,7 @@ nav:
|
|||
- Overview: Security/Framework/Overview.md
|
||||
- Quorum Network:
|
||||
- Consortium: Security/Framework/Quorum Network Security/Consortium.md
|
||||
- Quorum Node:
|
||||
- Quorum Node:
|
||||
- Overview: Security/Framework/Quorum Network Security/Node.md
|
||||
- Permissioning:
|
||||
- Network Permissioning: Security/Framework/Quorum Network Security/Nodes/Permissioning/Network Permissioning.md
|
||||
|
|
@ -64,7 +66,7 @@ nav:
|
|||
- How it works: Privacy/Constellation/How constellation works.md
|
||||
- Sample Configuration: Privacy/Constellation/Sample Configuration.md
|
||||
- Running Constellation: Privacy/Constellation/Installation & Running.md
|
||||
- Product Roadmap: roadmap.md
|
||||
- Product Roadmap: roadmap.md
|
||||
- FAQ: FAQ.md
|
||||
|
||||
theme:
|
||||
|
|
|
|||
Loading…
Reference in New Issue