Updated 2019-12-17

Private Network Quickstart Tutorial

The Private Network Quickstart uses the Hyperledger Besu Docker image to run a private network of Besu nodes managed by Docker Compose.


The Private Network Quickstart runs a private network suitable for education or demonstration purposes. The Private Network Quickstart is not intended for running production networks.


To run this tutorial, you must have the following installed:

  • MacOS or Linux


    The Private Network Quickstart is not supported on Windows. If using Windows, run the quickstart inside a Linux VM such as Ubuntu.

  • Docker and Docker-compose

  • Git command line

  • Curl command line

  • A web browser that supports Metamask (currently Chrome, Firefox, Opera, and Brave), and has the MetaMask plug-in installed. This tutorial uses screenshots from Brave.

Clone Besu Quickstart Source Code

Clone the repository from the besu-quickstart repository:

git clone https://github.com/PegaSysEng/besu-quickstart.git


Download a specific release at https://github.com/PegaSysEng/besu-quickstart/releases.

Build Docker Images and Start Services and Network

This tutorial uses Docker Compose to assemble the images and run the private network. To build the docker images and run the containers, go to the besu-quickstart directory and run:


The run.sh script builds the images, and runs the containers. It also scales the regular node container to four containers to simulate a network with enough peers to synchronize.

When the process ends, it lists the running services:

Docker-compose services list example

Besu Quickstart <version>
List endpoints and services
              Name                            Command               State               Ports
besu-quickstart_bootnode_1     /opt/besu/bootnode_sta ...   Up      30303/tcp, 8545/tcp, 8546/tcp
besu-quickstart_explorer_1     nginx -g daemon off;             Up>80/tcp
besu-quickstart_grafana_1      /run.sh                          Up      3000/tcp
besu-quickstart_minernode_1    /opt/besu/node_start.s ...   Up      30303/tcp, 8545/tcp, 8546/tcp
besu-quickstart_node_1         /opt/besu/node_start.s ...   Up      30303/tcp, 8545/tcp, 8546/tcp
besu-quickstart_node_2         /opt/besu/node_start.s ...   Up      30303/tcp, 8545/tcp, 8546/tcp
besu-quickstart_node_3         /opt/besu/node_start.s ...   Up      30303/tcp, 8545/tcp, 8546/tcp
besu-quickstart_node_4         /opt/besu/node_start.s ...   Up      30303/tcp, 8545/tcp, 8546/tcp
besu-quickstart_prometheus_1   /bin/prometheus --config.f ...   Up      9090/tcp
besu-quickstart_rpcnode_1      /opt/besu/node_start.s ...   Up      30303/tcp, 8545/tcp, 8546/tcp

Followed by a list of the endpoints:

Endpoint list example

JSON-RPC HTTP service endpoint      : http://localhost:32768/jsonrpc
JSON-RPC WebSocket service endpoint : ws://localhost:32768/jsonws
GraphQL HTTP service endpoint       : http://localhost:32768/graphql
Web block explorer address          : http://localhost:32768
Prometheus address                  : http://localhost:32768/prometheus/graph
Grafana address                     : http://localhost:32768/grafana-dashboard                                                                        
  • Use the JSON-RPC HTTP service endpoint to access the RPC node service from your Dapp or from cryptocurrency wallets such as Metamask.
  • Use the JSON-RPC WebSocket service endpoint to access the web socket node service from your Dapp.
  • Use the GraphQL HTTP service endpoint to access the HTTP GraphQL node service from your Dapp.
  • Use the Web block explorer address to display the block explorer web application. View the block explorer by entering the URL in your web browser.
  • Use the Prometheus address to access the Prometheus dashboard.
  • Use the Grafana address to access the Grafana dashboard.

To display the list of endpoints again, run:


Block Explorer

This tutorial uses the Alethio Ethereum Lite Explorer.

Run the Block Explorer

Access the explorer by copying and pasting the Web block explorer address displayed when starting the private network to your browser.

The block explorer displays a summary of the private network:

Block Explorer

Notice that the explorer indicates 6 peers: the 4 regular nodes, the mining node and the bootnode.

Click the block number to the right of Best Block to display the block details:

Block Details

You can explore blocks by clicking on the blocks under Bk on the left-hand side.

You can search for a specific block, transaction hash, or address by clicking the magnifying glass in the top left-hand corner.

Explorer Search

Monitoring nodes with Prometheus and Grafana

The quickstart also includes Prometheus and Grafana monitoring tools to let you visualise the nodes health and usage. You can directly access these tools from your browser at the addresses displayed in the endpoint list.

For more details on how to configure and use these tools for your own nodes, refer to our performances monitoring documentation, as well as Prometheus documentation and Grafana documentation.


Run JSON-RPC Requests

You can run RPC requests on rpcnode, the node exposed to the host in order to listen for requests. This tutorial uses cURL to make JSON-RPC requests.

For the RPC URL, this tutorial uses the placeholder <http-rpc-endpoint>. When you run the tutorial, replace this placeholder with the JSON-RPC HTTP service endpoint provided when you list the endpoints. (For example, http://localhost:32770/jsonrpc.) The dynamic docker port mapping changes each time you run the network.

Click the button to import our collection of API examples to Postman.

Run in Postman

Requesting the Node Version

Run the following command from the host shell:

curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' <http-rpc-endpoint>

The result specifies the client version:

   "jsonrpc" : "2.0",
   "id" : 1,
   "result" : "besu/<version number>"
Here we simply query the version of the Besu node, which confirms the node is running.

Successfully calling this method shows that you can connect to the nodes via RPC. From here, you can walk through more interesting requests demonstrated in the rest of this section, or skip ahead to Creating a Transaction Using MetaMask.

Counting Peers

Peers are the number of other nodes connected to the RPC node.

Poll the peer count using net_peerCount:

curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' <http-rpc-endpoint>

The result indicates that there are 6 peers:

  "jsonrpc" : "2.0",
  "id" : 1,
  "result" : "0x6"

Requesting the Most Recently Mined Block Number

Call eth_blockNumber to retrieve the number of the most recent block:

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' <http-rpc-endpoint>

The result provides the most recently mined block:

  "jsonrpc" : "2.0",
  "id" : 1,
  "result" : "0x8b8"

The hexadecimal value 0x8b8 translates to 2232 in decimal, the number of blocks that have been mined so far.

Checking the Miner Account Balance

Call eth_getBalance to retrieve the balance of the mining address (coinbase) defined in the miner node:

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","latest"],"id":1}' <http-rpc-endpoint>

The result specifies the miner account balance:

  "jsonrpc" : "2.0",
  "id" : 1,
  "result" : "0x79f905c6fd34e80000"


0x79f905c6fd34e80000 = 2250000000000000000000 Wei (2250 Ether).


Use a unit converter to easily translate values from Wei to Ether.

Wait several seconds until new blocks are mined and call eth_getBalance again. The balance increases, meaning the miner address successfully received the mining reward.

You can also view this information in the block explorer. It does exactly the same thing as this call, connecting to the RPC node using HTTP JSON-RPC, and displaying information on a web page.

Creating a Transaction Using MetaMask

Now let’s use MetaMask to send transactions.

Before sending transactions, you need to create an account or use one of the accounts below created during the genesis of this private test network.


Do not use the following accounts on mainnet or any public network except for testing.

The private keys are displayed here which means the accounts are not secure.

Account 1 (Miner Coinbase Account)

  • Address: 0xfe3b557e8fb62b89f4916b721be55ceb828dbd73
  • Private key : 0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63
  • Initial balance : 0xad78ebc5ac6200000 (200000000000000000000 in decimal)

Account 2

  • Address: 0x627306090abaB3A6e1400e9345bC60c78a8BEf57
  • Private key : 0xc87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3
  • Initial balance : 0x90000000000000000000000 (2785365088392105618523029504 in decimal)

Account 3

  • Address: 0xf17f52151EbEF6C7334FAD080c5704D77216b732
  • Private key : 0xae6ae8e5ccbfb04590405997ee2d52d2b330726137b875053c36d94e974d162f
  • Initial balance : 0x90000000000000000000000 (2785365088392105618523029504 in decimal


Besu doesn’t implement account management. To create your own account, you have to use a third-party tool such as MetaMask.

After you sign in to MetaMask, connect to the private network RPC endpoint:

  1. In the MetaMask network list, select Custom RPC.
  2. In the New RPC URL field, enter the JSON-RPC HTTP service endpoint displayed when you started the private network.

Save the configuration and return to the MetaMask main screen. Your current network is now set to the private network RPC node.

Import one of the existing accounts above into MetaMask using the corresponding private key.


In this tutorial, we don’t need to secure the keys, because we’re using a private test network to send valueless Ether. However, be sure to secure your accounts in a real use case on the main Ethereum network (MainNet).

Once this is done, create another account from scratch to send Ether to.

In MetaMask, select the new account and copy the account address by clicking the gadget and selecting Copy Address to clipboard.

In the block explorer, search for the new account by clicking on the magnifying glass and pasting the account address into the search box. The account is displayed with a zero balance.

Send Ether from the first account (containing ether) to the new one (which has a zero balance).

Refresh the browser page that displays the new account. The updated balance is displayed and reflects the transaction completed using MetaMask.

Truffle Pet Shop Tutorial

With a few modifications, we can use the private network in this tutorial as the blockchain for the PetShop tutorial on Truffle website.


Install Truffle and Unpack Truffle Box

Install Truffle :

npm install -g truffle


npm requires sudo on Linux.

Create a pet-shop-tutorial directory and move into it:

mkdir pet-shop-tutorial

cd pet-shop-tutorial

Unpack Pet Shop Truffle box:

truffle unbox pet-shop

Install the Truffle wallet: Note with Truffle 5, you must use a Web3 1.0 enabled wallet or the Truffle tasks will hang.

npm install --save @truffle/hdwallet-provider


npm requires sudo on Linux.

Modify the Pet Shop Example

Modify the truffle-config.js file in the pet-shop-tutorial directory to add our wallet provider. The following shows the code with placeholders to change as directed below:

const PrivateKeyProvider = require("truffle-hdwallet-provider");
const privateKey = "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63";

module.exports = {
  // See <http://truffleframework.com/docs/advanced/configuration>
  // for more about customizing your Truffle configuration!
  networks: {
    development: {
      host: "",
      port: 7545,
      network_id: "*" // Match any network id
    quickstartWallet: {
      provider: () => new PrivateKeyProvider(privateKey, "<YOUR HTTP RPC NODE ENDPOINT>"),
      network_id: "*"

Replace <YOUR HTTP RPC NODE ENDPOINT> with your HTTP RPC node endpoint (for example, http://localhost:32770/jsonrpc).

The private key is the miner address, which contains Ether.

Once this is done, follow the Truffle tutorial steps up to Step 3 in the Migration section.

We’re using the private network instead of Ganache, so skip steps 3, 4, and 5 in the Migration section.

In step 4, specify the private network:

truffle migrate --network quickstartWallet

Output similar to the following is displayed (your addresses will differ):

Using network 'quickstartWallet'.

Running migration: 1_initial_migration.js
  Deploying Migrations...
  ... 0xfc1dbc1eaa14fa283c2c4415364579da0d195b3f2f2fefd7e0edb600a6235bdb
  Migrations: 0x9a3dbca554e9f6b9257aaa24010da8377c57c17e
Saving successful migration to network...
  ... 0x77cc6e9966b886fb74268f118b3ff44cf973d32b616ed4f050b3eabf0a31a30e
Saving artifacts...
Running migration: 2_deploy_contracts.js
  Deploying Adoption...
  ... 0x5035fe3ea7dab1d81482acc1259450b8bf8fefecfbe1749212aca86dc765660a
  Adoption: 0x2e1f232a9439c3d459fceca0beef13acc8259dd8
Saving successful migration to network...
  ... 0xa7b5a36e0ebc9c25445ce29ff1339a19082d0dda516e5b72c06ee6b99a901ec0
Saving artifacts...

Search for the deployed contracts and transactions in the block explorer using the addresses displayed in your output.

Continue with the Truffle tutorial steps in the Testing the smart contract section.

To run the tests in the Running the tests section, specify the private network:

truffle test --network quickstartWallet

Output similar to the following is displayed:

Using network 'quickstartWallet'.

Compiling ./contracts/Adoption.sol...
Compiling ./test/TestAdoption.sol...
Compiling truffle/Assert.sol...
Compiling truffle/DeployedAddresses.sol...

    ✓ testUserCanAdoptPet (2071ms)
    ✓ testGetAdopterAddressByPetId (6070ms)
    ✓ testGetAdopterAddressByPetIdInArray (6077ms)

  3 passing (37s)

Continue with the Truffle tutorial steps in the Creating a user interface to interact with the smart contract section.

We’ve already connected the private network to MetaMask, so you can skip the Installing and configuring MetaMask section.

Continue with the regular tutorial steps from the Installing and configuring lite-server section and finish the tutorial.

When you adopt pets in the browser and approve the transaction in MetaMask, you’ll be able to see the transactions in the block explorer.

Stop / Restart Private Network without Removing Containers

To shut down the private network without deleting the containers:


This command stops the containers related to the services specified in the docker-compose.yml file.

To restart the private network:


Stop Private Network and Remove Containers

To shut down the private network and delete all containers and images created during the quickstart: