This series of tutorials will describe how to set up a private Ethereum blockchain that will be composed of a computer (miner) and one or several Raspberry PI 3 devices (nodes).

The objective is to build a development environment to learn about blockchain principles, to develop and test your own smart contracts before releasing them to the live chain (mainnet).

To make this project fun, we will integrate a RPi with a Smart Contract deployed on a private chain. The Smart Contract will be used to check if a user has enough tokens to use a service. The RPi will be used to visualize the status of the contract.

NB: It is important that what we mean by “private Ethereum blockchain” in this context has absolutely nothing to do with the “private blockchain” championed by Hyperledger, Eris/Monax, or the recently announced Enterprise Ethereum Alliance. These are different codebases with different client applications, so they correspond to different implementations of a different set of concepts. They are private in the sense that they limit who has access to their chain. They are also called permissioned blockchains, and to be perfectly transparent, we wish they were not even called blockchains at all. In this series of articles, what we call “private blockchain” is a private instance of the Ethereum implementation. Same code base, same client application, different network identifier and genesis block. In other words, what we will come to create in this series is a chain with the same rules as the main chain, the same consensus algorithm too, but a different root block. This will become clearer in part 3. For more information about the 3-layer model and differences between concepts, implementations and instances, you can also watch our Devoxx talk and read this article.


We will use the following naming conventions to identify the devices on which the commands are entered:

computer$ A computer requires to perform initial configuration

pi$ Shell of the node running on the Raspberry PI device


This series of tutorials doesn’t pretend to be comprehensive neither to give you a full introduction to Ethereum.

There are many ways to set up a private Ethereum blockchain from the most simplistic to the most complicated.

Here are some other examples:

  • Microsoft Azure and RPi  (here)
  • Docker image (here)
  • Pre-defined images such with EthRaspian (here)

Part 1: Install an Ethereum node on a Raspberry PI (RPi)

In this first part, we will describe the steps to transform your Raspberry PI 3 (RPi) into an Ethereum node.

The RPi is intended to act as a node connected to our private Ethereum blockchain. This means that it’s not required to install a full flesh operating system. A minimal image of Raspbian is good enough.

For information, there are pre-bundled RPi images that make it possible for you to transform your RPi into an Ethereum node.

One of these images is provided by the project EthRaspbian.

Here, we chose to build our Ethereum node without these prepared images. The objective is to show you all the required steps to do it from scratch.

Due to hardware limitations (CPU, memory), your RPi will not be able to mine ethers or to build new blocks of transactions.

Step 1 – Check your configuration

We will use a Raspberry PI 3 with a microSD of 16 Gb and a computer to prepare the microSD card.

The setup of the RPi will require the following hardware:

  • A Raspberry Pi
  • An SD Card with at least 16Gb
  • A LAN cable
  • A keyboard
  • A display

Step 2 – Format your SD Card

Insert your SD card on your computer and format it as FAT32.

On macOS, use the format ExFat in Disk Utility:

Step 3 – Write the Raspbian image

From your computer, download the Raspbian Jessie Lite image (minimal image) available here.

Unzip the file.

Write the image on the SD card by following instructions there. The process varies slightly depending on whether you are on a MacOS, Linux or Windows machine.

Here is an example for macOS (be very careful with the commands, every character matters):

computer$ diskutil list
/dev/disk5 (external, physical):

computer$ diskutil unmountDisk /dev/disk5

computer$ sudo dd bs=1m if=2016-11-25-raspbian-jessie-lite.img of=/dev/rdisk5

computer$ diskutil eject /dev/disk5

Ensure that your RPi is powered off.

Insert the SD card on you RPi and power on the device. Your RPi will boot the image.

Step 4 – Configure your RPi

Log in the RPi with the default credential is:

  • username: pi
  • password: raspberry

The RPi needs to be configured:

  • Change the keyboard layout (if required)
  • Set the timezone: required to allow a blockchain synchronisation between nodes
  • Enable SSH: securely access your RPi from your computer
  • Change your hostname: easily identified your RPi within your network (example: node1, node2, etc.)

We use raspi-config to setup all these settings:

pi$ sudo raspi-config

1) Timezone can be changed from the option "Internationalisation Options" and "Change Timezone".

2) Keyboard layout can be changed from the option "Internationalisation Options" and "Change Keyboard Layout". 

3) SSH can be enabled from the option "Advanced Options" then "SSH". 

4) The hostname can be changed from the option "Advanced Options" and then "Hostname. In our tutorial, we use the hostname "ethpinode1"

Press Finish and reboot your RPi:

p$> sudo reboot

Finally, you should really change the default password of the pi account:

pi$ passwd

Step 5 – Setup Wi-Fi

To setup your Wi-Fi interface, proceed as described below:

pi$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
  1. Change the country code to set yours
  2. Add the following lines at the end of the file and replace the ssid with the name of your WiFi and psk with your WiFi’s password:
 ssid="enter the SSID of your Wi-Fi network"
 psk="enter the password of your Wi-Fi network"

To apply your changes, restart your RPi or your Wi-Fi interface:

pi$ sudo ifdown wlan0
pi$ sudo ifup wlan0

You can now unplug  your LAN cable.

Step 6 – Connect to your RPI

To connect remotely to your RPi through SSH, you have to know the IP address of your RPi device.

You can find it by typing the following command from your RPi:

pi$ ifconfig

Or you can search it from your LAN by filtering IP adresses from a MAC  prefix address (b8:27:eb is the MAC prefix address of RPi devices):

computer$ arp -na | grep -i b8:27:eb
? ( at b8:27:eb:1c:aa:94 on en0 ifscope [ethernet]

If you have several RPi, you can locate them using the “host” command:

computer$ host domain name pointer ethpinode1.

At this stage, you can continue the setup of your RPI remotely from your computer using the “ssh” (“pi” is the username defined on your RPi):

computer$ ssh pi@

It’s time to install Ethereum.

Step 7 – Install Geth

In this step, we are going to install the Go implementation of Ethereum client called Geth.

Connect to your RPi and retrieve the type of your CPU:

pi$ cat /proc/cpuinfo
model name : ARMv7 Processor rev 4 (v7l)

Go to the download page of Go-Ethereum by clicking here.

Select the tab Linux from the stable releases page.

Locate the row related to your CPU model and copy the link address . It’s recommended to retrieve the latest version of Geth.

In our example, we use Geth 1.5.7.

Back to your RPi, retrieve the bundle and extract the archive:

pi$ wget

pi$ tar zxvf geth-linux-arm7-1.5.7-da2a22c3.tar.gz 

Copy the Geth application to the /usr/local/bin folder:

pi$ cd geth-linux-arm7-1.5.7-da2a22c3

pi$ sudo cp geth /usr/local/bin

You can remove the archive and the uncompressed folder.

Check the version of Geth:

pi$ geth version
Version: 1.5.7-stable
Git Commit: da2a22c384a9b621ec853fe4b1aa651d606cf42b
Protocol Versions: [63 62]
Network Id: 1
Go Version: go1.7.4
OS: linux

The same process can be applied to update an existing version of Geth.

Now, Ethereum is installed.

Let’s start it!

Step 8 – Run Geth

Start Geth using the following command:

pi$ geth
I1217 19:11:27.420830 p2p/server.go:342] Starting Server
I1217 19:11:39.816110 eth/downloader/downloader.go:326] Block synchronisation started

Press CTRL-C to stop the Ethereum server.


At this stage, Ethereum is installed on your RPi and able to synchronise with the live chain (mainnet).

The blockchain data (chaindata) is located right here: ~/.ethereum/chaindata

Your accounts will be stored in a wallet located in this folder: ~/.ethereum/keystore

Congratulations! Your RPi is an Ethereum node.

You can repeat these steps to setup additional RPi.

Part 2 describes how to set up Ethereum on a computer.

Shameless plug

While you are waiting for the next part of this series, we just wanted to let you know that we are currently preparing a full-blown online training about the development of distributed applications on Ethereum and we are looking for your feedback to figure out what you would like to see in this training. If you want to help us, you can take a few minutes to answer a survey here.

And if you just want us to keep you informed when the full online training program will be available, you can register to our mailing list on

Said Eloudrhiri