Setting Up and Running a Private Ethereum Blockchain on Ubuntu

Introduction

In this post I will go over detailed steps on how to setup a private Ethereum blockchain on an Ubuntu 16.04 LTS instance. These steps should work on any modern Ubuntu operating system as well as many other Linux distros. The primary issue I had that led me to create this post was that there weren't any good documents on how to set up an Ethereum private instance. Currently a lot of corporations are looking to hire people with skills programming with an Ethereum blockchain, so this is certainly an extremely valuable skill to have.

Setup

In this guide I will assume you have Ubuntu already installed on your computer and ready to go. If you don't please head on over to the Ubuntu website and get a copy of Ubuntu 16.04 LTS (don't worry it's free). After you have Ubuntu installed, install go-ethereum by following the steps on this GitHub page. Incase that page goes down, I have also listed the steps here:

Installing from PPA as listed on the go-ethereum GitHub page

sudo apt-get install software-properties-common
sudo add-apt-repository -y ppa:ethereum/ethereum
sudo apt-get update
sudo apt-get install ethereum

If you happen to be on other Linux operating systems you can also install geth from source.

Running from a remote cloud instance

If you are setting up your private blockchain on a cloud instance make sure ports 30303 and 8000 are accessible via TCP (you'll need to change this in your cloud instance settings if you're using AWS or similar). If you're only going to be using your blockchain locally don't worry about this for now.

Directory structure and files

In order to stay organized it's a good idea to first start out and create some necessary folders. For now lets create a folder in our home directory called priv. Open up the Terminal application, and type the following commands:

cd ~
mkdir priv
cd priv
mkdir config
mkdir data
mkdir scripts

After this you should have a priv directory located at /home/$USER/priv where $USER is your username, and you should have the directories /home/$USER/priv/config, /home/$USER/priv/data, /home/$USER/priv/scripts.

Defining the genesis block

In this step we are going to create a file called CustomGenesis.json that contains data regarding our initial genesis block. Do the following steps to create this file:

cd ~/priv/config
touch CustomGenesis.json

Now you should have an empty file called CustomGenesis.json located at /home/$USER/priv/config/CustomGenesis.json Next open the file in your favorite text editor for simplicities sake we will use gedit which ships by default with Ubuntu, and copy-paste the following contents into the file:

/home/$USER/priv/config/CustomGenesis.json

{
   "config": {
        "chainId": 424242,
        "homesteadBlock": 0,
        "eip155Block": 0,
        "eip158Block": 0
    },
    "nonce": "0x0000000000000042",
    "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "difficulty": "0x400",
    "alloc": {},
    "coinbase": "0x3333333333333333333333333333333333333333",
    "timestamp": "0x00",
    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "gasLimit": "0xffffffff",
    "alloc": {
        "8df9a875a174b3bc565e6424a0050ebc1b2d1d81": { "balance": "500042" },
        "g41c74c9ae680c1aa78f42e5647a62f353b7bddf": { "balance": "600042" }
    }
}

This file defined the initial block configuration of our private blockchain. Save the file by doing File -> Save, now we're ready to move on to the next part which is actually initializing our private Ethereum blockchain.

Initializing the blockchain with the genesis block

Now that we have defined our genesis block the next step is to create a script that initializes our private blockchain, we will create a file called INIT_PRIV_CHAIN.sh and give it executable permissions. Follow these steps to create that file:

cd ~/priv/scripts
touch INIT_PRIV_CHAIN.sh
chmod +x INIT_PRIV_CHAIN.sh

Open up INIT_PRIV_CHAIN.sh using gedit by doing:

 gedit /home/$USER/priv/scripts/INIT_PRIV_CHAIN.sh

Copy-paste the following contents into the file and save:

/home/$USER/priv/scripts/INIT_PRIV_CHAIN.sh

#!/bin/sh

DATADIR=/home/$USER/priv/data
GENESIS=/home/$USER/priv/config/CustomGenesis.json
NETWORKID=42
IDENTITY="MyPrivateChain"
PORT=30303
RPCPORT=8000

# Initialize the private blockchain
geth --networkid $NETWORKID --datadir=$DATADIR --identity $IDENTITY --port $PORT --rpcport $RPCPORT init $GENESIS

Now we can finally initialize our private Ethereum blockchain by running the script by doing:

cd ~/priv/scripts
./INIT_PRIV_CHAIN.sh

Congratulations you have successfully initialized a private Ethereum blockchain!

Creating a daemon to keep the private blockchain running in the background

Now that we have successfully initialized our blockchain, let's create a daemon to make it such that our blockchain node runs in the background. For this step we will create another script called START_CHAIN_DAEMON.sh and give it executable privileges. To do this we do:

cd ~/priv/scripts
touch START_CHAIN_DAEMON.sh
chmod +x START_CHAIN_DAEMON.sh

Now just as before open START_CHAIN_DAEMON.sh with gedit by doing:

gedit /home/$USER/priv/scripts/START_CHAIN_DAEMON.sh

After doing this copy-paste the following contents and save:

/home/$USER/priv/scripts/START_CHAIN_DAEMON.sh

#!/bin/sh
PORT=30303
RPCPORT=8000
NETWORKID=42
IDENTITY="MyPrivateChain"
DATADIR=/home/$USER/priv/data
NAT=none
RPCADDR="0.0.0.0"

nohup geth --rpc --ws --port $PORT --rpcport $RPCPORT --networkid $NETWORKID --datadir $DATADIR --nat $NAT --identity $IDENTITY --rpcaddr $RPCADDR --wsaddr $RPCADDR --rpccorsdomain * &

Now we can finally run our private Ethereum blockchain by running the script by doing:

cd ~/priv/scripts
./START_CHAIN_DAEMON.sh

This will make it such that our private chain is running in the background, to stop the chain you can do:

ps ax | grep "geth"

This will list all of the processes that are associated with geth to stop the process find the process id associated with geth and do kill -term XXXX that number where XXXX is that process id.

Connecting to the blockchain and executing remote calls via a JavaScript console

Now that the private Ethereum blockchain is up and running, we can communicate with the blockchain by doing:

geth attach http://0.0.0.0:8000

in a local terminal session, if you have a cloud instance with port 8000 open as well as port 30303 you can communicate with the blockchain remotely from any computer by doing:

geth attach http://X.X.X.X:8000

where X.X.X.X is your cloud instance's public IP address.

What's next?

Now that you have a private Ethereum blockchain running you can look into developing and deploying smart contract based applications using TruffleJS or you can try developing using ConsenSys' JSONRPC Python library Ethjsonrpc. You can also develop native decentralized applications using the Native Ethereum Go Bindings.

Conclusion

I hope you enjoyed this post on setting up and running a private blockchain on an Ubuntu instance. If you have any corrections, suggestions, or corrections please comment below.

Cheers
~Np