Raspberry Pi-4 Node
A guide for developers wanting to setup a Cardano node for development purposes using a Raspberry Pi 4. This guide is not a How-to for starting a stake pool!
Last updated
A guide for developers wanting to setup a Cardano node for development purposes using a Raspberry Pi 4. This guide is not a How-to for starting a stake pool!
Last updated
Don't worry, setting up a regular node is easy - Nobody (2022)
At Revelar, we very quickly realized we needed to have some kind of development sandbox to write and test on-chain code. Being that we're also a bunch of hardware nerds, we decided to build a 3 Pi cluster and add RGB. As we went through the process of setting up a Cardano node, we encountered a lot of difficulty mostly because all of the information for our use case, was fragmented and spread out everywhere. So this guide presents all the information needed to setup a cardano-node on a Pi 4 to create a development platform.
So if you are looking for a guide to setup a Cardano node on a Raspbian based Pi 4 for the purpose of doing development or cardano-cli tasks, then this is the right guide.
Raspberry Pi 4 8GB 64-bit
Heat-sink with a fan (Something like this)
Type C Power Supply
NVME M.2 SSD with at least 256gb
NVME M.2 to USB3.0 Case
Ethernet Cable (If not using wifi)
Computer Mouse, Keyboard and monitor
As of the date of writing, we have only created a node on a Raspberry Pi 4 with 8GB of RAM. Most literature online will also advise you to use an 8GB Pi so we suggest you also get an 8GB version.
You also REQUIRE a heatsink for the Raspberry Pi. One of the steps in this tutorial overclocks the Pi and for that you do NEED a heatsink. We recommend a single piece unit with an integrated fan.
We recommend that you get an NVME SSD as it greatly increases the speed of storage
Before we can do anything we first need to setup the operating system on our Raspberry Pi 4. There are many ways to go about this, for simplicity's sake, we just went with the standard Raspbian OS.
This is the tool we will use to load an operating system onto the Pi. This tool can be downloaded from raspberrypi.com.
In this guide, we will use the standard Raspberry Pi OS. The OS can be downloaded from the official site.
Scroll down on the website and download the Raspberry Pi OS with Desktop. The picture below shows the latest version as at the time of writing. You may need to download a newer version if it is available.
Once downloaded, extract the file into an empty folder. You should now have a disc image file in that file titled something like 2022-01-28-raspios-bullseye-arm64.img.
Now connect your NVME SSD via USB and open Raspberry Pi Imager.
The Imager will have three options to choose from. Under Operating System, scroll down the list and choose the Use Custom option. In the popup navigate to the Disc Image file we downloaded in the previous step.
Next, select the name of your drive under the Storage option. Lastly click on Write to start the process of writing an OS to the SSD. You will be asked to erase all data on disk to which you must say Yes.
Now you just wait for the process to complete. It usually takes a couple of minutes.
Once you have loaded an OS, you are ready to start with booting up your Pi. For the first time, you will require a keyboard, mouse and monitor to be directly connected to the Pi.
Make sure the Pi is now pluged in. Connect the HDMI, keyboard, mouse and SSD. Then only power it on. Give it a minute or two to read the OS from the SSD. Once done, navigate through the prompts. For sake of brevity I won't add screenshots here, as the prompts are pretty self explanatory however the general process is as follows.
Once you have booted into the OS, you will have a popup saying something to the effect Welcome to Raspberry Pi... This is the start ofthe setup wizard so click next.
Set Country, language and Timezone
Change the Password for the default Pi user. This is your own preference although we strongly recommend you do change the password.
Setup the Screen
Connect to WiFi (or Ethernet in which case you simply skip)
Update Software (This is optional although you can skip this as we will be doing it later on anyways)
Restart the Pi
If you would like to access your Pi remotely from the same network, follow these steps to enable VNC access.
Open the Start Menu (Pi Logo in the top left), navigate to the Preferences tab and select the Raspberry Pi Configuration option.
You should see the Raspberry Pi Configuration GUI. Under the Display tab, disable Screen Blanking and choose the Headless Resolution that you want to see when you access the Pi remotely.
Under Interfaces tab, enable VNC. Alternatively you could use SSH. If you want to setup SSH, here are the official docs on how to do so with a Pi.
Once all the options are set, reboot the Pi.
Once you have completed a reboot and logged into the Pi again. In the corner of the Taskbar you should now have a VNC logo. Click on it to open the VNC screen. Here is a tutorial for how to connect to VNC.
Open a terminal and run the following command to update the software on the Pi.
Once completed run the following two commands to clean up any temporary files created during the update process.
You can configure the Pi to automatically install new security updates using the unattended-upgrades package. This is not a required step.
First install the required package (if it isn't installed already).
Then configure it using the command below.
Do not do this step if you do not have a heatsink installed! Overclocking a Pi without a heatsink could lead to thermal damage!
The Raspberry Pi 4 can safely be overclocked to run at 2GHz and that is the highest we will go in this guide. By safely we mean the resultant overclocked Pi is stable and does not void the warranty.
Overclocking the Pi 4 beyond 2GHz is possible, however it will void your warranty. If you want to overclock beyond 2GHz, do your own research!
To overclock we need to edit the /boot/config.txt file. You can use any text editor to do so, I use nano
Scroll down to the following lines:
Just below this add in the following:
Save the file (Ctrl-S & Ctrl-X), and reboot the Pi.
This is usually a very important step for those looking to run a Stake-pool. The intent of this guide is to setup a node for development and testing purposes, as such we will not run down a full cybersecurity rabbit hole to try to cover every Linux/Ubuntu attack vector that exists. Instead we will give some best practices we recommend in this section.
This is not an optional section as we will be making changes to the system config that we need later on!
If you do however want to harden your Pi to the full extent, here is a great guide and Here is another guide with ways to harden Ubuntu (which also work on Raspberry Pi). Be warned though, this is a rather deep chasm of a rabbit-hole.
Processes/Programs can use the RAM to communicate with one another within Linux, hence the name shared memory. However by default the permissions for this are set to both read and write, which introduces a memory attack vulnerability. So in this subsection we will change those permissions to read only.
First we open the file where we will set the permissions:
Then we will add the following to the end of the file:
The contents of this section are taken from here which was in turn based off suggestions contained here. The second of those links will set you down a security rabbit trail so be wary.
The changes here largely help secure the network config for the Pi and provide protection against a number of networking based exploits.
First we need to edit the sysctl.conf file.
Once opened, post the following into the end of the file. Lines 34-38 are Kernel parameters added as part of the Zram install process, which we will do later in this section.
In order to ensure that these changes are enforced at every boot, we also need to edit the rc.local file. To do this first open the file:
Then edit your file to look like this:
This will ensure that the correct config is loaded.
The cardano-node process is quite memory intensive and will open a lot of files. This step ensures that you do not encounter a max file limit.
This is accomplished by adding two lines to the limits.conf file in /etc/security/. This can be accomplished with the following inline Bash command:
This will add the following lines to the end of the file:
Time synchronization is extremely important for a functioning node. So to ensure that our synchronization is as accurate as possible, we will install and configure Chrony. Chrony is a package that syncs up the time with various reference clocks using the Network Time Protocol.
First we need to install the package:
Next we need to configure chrony and tell it where it should sync time to. First open the config file:
Then copy and past the following into the config file:
The restart the service to load the new config:
In order for cardano-node to run properly we need to add more RAM. Even 8GB won't be enough. So to add this RAM, we use ZRAM to do some clever memory magic to effectively boost 8GB to 20GB. Here is a better explanation of what this magic is.
First we disable the standard SWAP on the Pi:
Next, install ZRAM:
Once completed, we need to edit the config file to achieve the appropriate boost:
Then change the file to look as follows:
Once you have done all of the above, REBOOT.
It is crucial that ZRAM be functional before installing and syncing the cardano-node
Once you have rebooted, open an terminal verify ZRAM:
Your output should look something like this:
You can also verify using htop:
You should see a Swp of aboput 11.4GB.
Finally, we have arrived at the main event, installing and syncing a Cardano node. Be ye forewarned though, this step involves a lot of waiting as we will be building and installing a node using Cabal.
When I created this guide, I specifically wanted to go through the process of building as I wanted to know what it looked like and what it entailed, as I'm sure other devs would want to do as well.
First though we need to install the dependencies
The first chunk of dependicies that need to be installed are standard Linux packages that can be installed via apt.
The next requirement is to install Cabal and GHC. We found that using ghcup is the quickest way to do this.
To start, we run the following:
This will start a guided installer for Haskell, Cabal, and GHC.
When asked if you want ghcup to auto-add the required PATH variable, say yes
Since this is a development machine, you can say yes for the Haskell language server as invariably you might end up using it
You do not need to install stack
You should not need to install any more packages as we have already done that
Now you just need to wait for the installation process to complete. Once the installation has completed, you need to restart.
Once the reboot completes, open a terminal and test the install using GHCi. From the terminal just type ghci. If the GHCi interface opens then the install has been completed successfully.
You also need to verify that cabal has been installed correctly:
After the install, we need to tell ghcup to use specific versions of Cabal and GHC. Dependancies and packages in Haskell can get iffy so always stick to the recommended versions.
The following commands will build the directories.
Having all the configuration and environment variables stored in a file makes things a little easier to manage. Below are the commands needed to initialize a .env file. You can choose either mainnet or testnet.
Initialize the .env file that will be used to store all our environment variables.
Now that environment file has been created, we can populate it with all the variables we want it to contain.
Libsodium is required to build the cardano-node. The following commands will build the libsodium environment.
Once installed add the necessary values to the bash file and update the link cache:
This will retrieve the topology files needed to build the node. We will grab the NODE_CONFIG variable from our .env file. This will download the topology files corresponding to either the testnet or the mainnet.
Navigate to the folder for the source code we previously created and clone the source code repository.
Once cloned, we need to check out the latest version of the cardano-node. Scroll through the output of git tag and make sure you get the latest version of the cardano node. At the time of writing the latest is 1.34.0.
The following steps need to be performed if you are building from source-code (which we are doing). The build process requires an LLVM installation, however just installing an LLVM does not work. The following solution is the same solution as used on the Mac-M1 cardano-node build.
This process can take up to a couple hours so don't be surprised if it takes very long
The build process can take a long time (about 2 hours). So just be patient until it is done.
First we need to tell Cabal which version it has to use to build the node. This tells Cabal to use the version we installed earlier. This step takes bout 3 minutes to complete.
Now we start the build process. This step will take a couple hours. Our build times varied between 2 and 6 hours.
Once the build is done, we need to copy the commands into the bin file and add that to bash
This process is the long one. It can take up to 48 hours to fully sync with the tip of the blockchain.
For convenience's sake we will put the node command into a bash script.
Next copy the following into the script file:
Save and close the file. Then we need to make sure we can execute the script, this is done with the following command.
Now you can start the sync
This process is the real time consumer, here we are going to start the node which will start the syncing process.
To make this easier, we will put the cardano-node command inside a bash script. First we need to create a script file and make it executable.
Copy the following command into the file. Remember to copy in your username in the second line.
Save and exit the text editor. To run the script in your terminal we use the following command:
The guild operators github repository contains a number of helper scripts developed for stake pool operators. In our case, we are interested in only one of these scripts, the live viewer.
This script provides us with some visualization of what our cardano node is doing, or how far along in the process it is.
First we are going to clone it into our directory structure and make it executable.
Once that is done, we need to edit the env file that the gLiveView uses to tell it where all our data is.
Open the env we copied in your preferred text editor:
Next, edit the top (just below the User Variables heading) of the file to look like the following:
Then run the script:
Prometheus is a way to setup a data stream to export metrics from the device to an HTTP endpoint. From here you can use Grafana to build a dashboard of data from a remote system. In this guide we will only construct a localhost version of the dashboard.
If you want to access the dashboard remotely, you need to set up a proxy to route external traffic to the IP address of the Grafana localhost. This can be done using Nginx as a reverse proxy, an example of which is given in the Nginx docs. Armada Alliance also have a section in their Raspi-node guide that gives another way to do this (Armada Alliance's way is a lot less tedious and includes encryption).
First we need to install Prometheus and the Prometheus node-exporter. The latter of the two provides metrics about the state of the hardware and the kernel of the system. Once installed we are also going to disable both, so that we can update their configs.
Prometheus by default scrapes the localhost:9100 endpoint. We want to add the port location for our cardano-node as well. This port is 12978, so we are going to add that to the config file:
Lastly, we want to restart the service so that Prometheus is reactivated with the new config.
You can test your data exporting by using a web browser to navigate to the following endpoints:
These two endpoints should show a text list of parameters and their respective values.
Before you can install Grafana, you need to add the repository to Raspbian.
We encountered issues with the standard Chromium browser on Raspbian and Grafana. If you find the standard browser to be slow or unresponsive try installing Firefox.
Next we can install Grafana:
To get started with Grafana, first open the config file and ensure that the port Grafana is working on, is different from any of the other ports used to operate the Cardano node or Prometheus:
Navigate to the http_portline and pick a port that is unused. We chose port 5000.
Next, use a browser and navigate to http://localhost:5000
The first time you open Grafana, you will be prompted to enter a username and password. The default is admin for both.
Once you make it to the home page of Grafana, you first need to add Prometheus as a datasource. To do this, navigate to the Gear icon on the left, click on the Data Sources tab, and choose the Add data source option.
At the top of the list, Prometheus will be listed. Click on it to navigate to the config page.
On the config page, make sure to type in the URL as http://localhost:9090
Once configured, you can start by building your first dashboard!
Armada Alliance maintains a repo with a number of example dashboards that can be imported and reconfigured. Their example dashbopards are designed for stake pool operatos so you would need to reconfigure them to remove the non-relevant parts.
Grafana Labs also has very good documentation on how to create dashboards, should you choose to create your own dashboards from scratch.
This guide was based off a lot of good material contained in a number of Armada Alliance tutorials, specifically the following two:
Both of these guides served as the base upon which we built our own node cluster, and subsequently greatly influenced how we wrote this guide. We burned through a number of tutorials and we always ended up coming back to the Armada Alliance tutorials.
We also used the official IOHK Cabal Build Guide and the Cardano.org Guide to help us figure out how to build the required code from source.
