Welcome to the Ethnetwork project, a standalone Dockerized Ethereum network with monitoring.
This Docker image is based on ethereum/client-go:alpine
docker image,
released by Ethereum team. The build is completely configurable, and sets up a
virtual docker subnet and to launch and initialize one Ethereum miner node, two
Ethereum nodes, one monitoring server, and one monitoring client, using a
single Docker image.
GNU make and Docker version 1.12 (or higher) are required. Internet connection is needed only for building the docker image. The project has been tested to work on Linux and MacOS X.
From git, clone the project:
git clone https://github.com/ing-bank/ethnetwork.git
Enter the source subdirectory and build the image:
cd ethnetwork
make build
.
├── artifacts
│ ├── app.json
│ ├── credentials.buyer
│ ├── credentials.carrier
│ ├── credentials.inspector
│ ├── credentials.miner
│ ├── credentials.node1
│ ├── credentials.node2
│ ├── credentials.seller
│ ├── entrypoint.sh
│ ├── genesis.json
│ ├── key.miner
│ ├── key.node1
│ ├── key.node2
│ ├── script1.js
│ └── static-nodes.json
├── Dockerfile
├── Makefile
└── README.md
Dockerfile
: the receipe to build the ing-bank/ethnetwork docker image
Makefile
: to build the image, initialize- and start and stop Ethereum
and monitoring nodes.
README.md
: this file
Most of the files found in ./artifacts
folder will be copied to the Docker
container and are used by the different containers.
genesis
: this is the genesis block used to initialize the Ethereum nodes,
contains network id and difficulty setting for Proof-of-Work.
script1.js
: a sample javascript which shows how much ether each account has.
This function can be installed on the geth prompt '> '
static-nodes.json
: the configuration file, which contains the nodes ip
addresses and node ids to connect to on startup.
credentials
: these files contain the account passwords. You can change the
individual account passwords by modifying these files. Do not forget to rebuild
the image.
entrypoint.sh
: the shell script executed by docker upon startup of the
container, takes the "role" parameter, returns help page when no role parameter
is provided.
Create a persistent data volume for the miner.
make datavolumes
The miner node requires a DAG file, that is generated if it does not exist. The generation takes around 8 minutes on a 2-GHz Intel processor. The DAG file is 1 GB in size. In order to avoid regenerating the DAG file every time we start up the environment, the DAG file will be stored in the persistent data volume. Note that the DAG file also gets automatically regenerated once per month.
To completely remove all the data volumes from your disk (and lose all data on these volumes for forever), use this command:
docker volume rm `docker volume ls -q`
To start up your personal Ethereum network, start all the components with one command:
make start
This will create a separate virtual network called "icec" in Docker, will
launch one miner node, two normal nodes, the monitoring client, and the
monitoring server nodes, all from a single docker image. The network range for
the virtual docker network is defined in the Makefile. Each container has its
own pre-configured ip address within the specified network range. Ethereum
miner and two nodes cross-connect to each other, as configured in
static-nodes.json
file. The miner node is the only one mining, using a single
cpu core. The monitoring node polls the miner and the nodes via the rpc port
30303, and publishes its results to the monitoring server.
The topology of the virtual network is reflected in the following diagram:
|-----(corp. lan)-----------+-----|
|
|--(virt. docker lan)----+------+------+-------+-----------+
| | | | |
miner nodeX node2 monitoring monitoring
server client
http://localhost:3000 - when the environment has been started, you will be able to see the environment statistics on this dashboard page. The monitoring server serves the visual dashboard page on the ethereum network. It connects via rpc protocol through the 30303 port to the network nodes and exposes its port 3000, which is mapped to the host. Montitoring requires the monitoring client to be active. The monitoring client will gather the state details from the three ethereum nodes (miner, node1, and node2) and will pass these details on to the monitoring server. Only after both the monitoring server and the monitoring client are active the dashboard will show the network state and health information.
To inspect the network and see what's in there simply run the following docker command:
docker network inspect icec
Geth console (on the miner node) can be envoked by a simple make command:
make console
Now you will see the Ethereum prompt '> ' this is where you can run geth (go-Ethereum) commands. Run the command below to get the basic Node information:
admin.nodeInfo
See how many peers are connected to the node:
admin.peers
Create an Ethereum account (password-protected by default):
personal.newAccount("<the_password_of_your_choice>")
Stop the geth console and return to shell:
> exit
Note1: There is no account name in this construct. All account in the Ethereum node are identified through an index (0, 1, 2, ...). You will need to keep track in your application which (functional)account is mapped to which index.
Note2: The password that you provide is the private key for the account. Please record this key, as it will be required when you would like to do something usefull with the account. Every transaction on Ethereum requires you to unlock that account first, and for this step you do need to specify this private key.
To stop the environment, run this command:
make stop
To remove the temporary docker containers and the network (but not the persistent volume), run this command:
make clean
Copy-paste the following script your geth console and then run this script to see the balances (in Ether) of all the accounts that live in the network:
function checkAllBalances() {var i =0;eth.accounts.forEach( function(e){console.log
("eth.accounts["+i+"]: " + e + " \tbalance: " + web3.fromWei(eth.getBalance(e),
"ether") + " ether");i++;})};
Step 1 - Enter the geth console
make console
Step 2 - Unlock the account (0) you want to transfer funds from
> personal.unlockAccount(eth.accounts[0],"g3heimpje")
Step 3 - Transfer the funds from account 0 to account 1
> eth.sendTransaction({from:eth.accounts[0],to:eth.accounts[1],value:1e10})
See https://github.com/ethereum/go-ethereum/wiki/geth how to use geth console and transfer Ether from one account to another.
The Ethereum network settings are highly configurable, and most settings are
set in the ./artifacts/genesis.json
file:
vi artifacts/genesis.json
genesis.json
file contains settings you can change:
nonce
- unique network iddifficulty
- how difficult the initial mining of ether should begasLimit
- how much gas is given to the network to run programsalloc
- names of the accounts and how much Ether each account gets
Note: every account will be initialized with 5000 Ether (5000 * 10000000000000000000 Wei) at the outset.
If you change genesis.json
file, you will need to rebuild your Docker image.
This is a development toolkit to quickly build Ethereum network in Docker. This is not meant to be a base for the production project. All RPC interfaces are exposed.
This concludes this mini tutorial. Your feedback and corrections are appreciated.
Toon Leijtens [email protected] and Maxim B. Belooussov [email protected] August-October 2016