Machu Picchu: Persistent IPFS node on Raspberry Pi3 — Part 2a

9 min readSep 7, 2021

Raspberry Pi3 Model B+ configured as IPFS node

version of September 6, 2021

The following is an explanation of how I installed a Raspberry Pi 3 Model B+ to serve as a persistent IPFS node in Machu Picchu. My Vision: Machu Picchu, Tech4Good

This document is composed of 3 parts, and a bonus:

Part 1 explains the Raspberry Pi and why it interests Machu Picchu. You may want to read it to get acquainted with this Single Board Computer and its very helpful community. It might also give you ideas how to use it for your own project.
Part 2a is a hands-on list of steps to install and deploy IPFS on the Raspberry Pi. It describes the first steps, until and including when changing the hostname and ssh password. This is what you are reading.
Part 2b is the rest of the steps to finish establishing a ssh session and the Solid State Disk, to install and deploy IPFS on the Raspberry Pi.
Bonus is the same as Part 2a but installs the system in 64-bit mode with Ubuntu, instead of 32-bit mode with Raspbian.

Although I’m doing my best to explain each step, at some point I needed to make assumptions about your knowledge of Linux. If you need more explanations, you might want to do a Google search for more details. Your lifesaver, whenever you are puzzled by an error message in the installation, is to paste in Google the text of the error message followed by “stackexchange”.

Machu Picchu Tech4Good, IPFS & blockchain

Machu Picchu is why I’m installing this IPFS node. Here is a quick description of concepts used in Machu Picchu if you are new to it.

IPFS is an Internet protocol to decentralize storage of data.
The persons-in-need can publish their profile data and their needs using IPFS. Like what we do on LinkedIn, but here each person keeps ownership of the data, and it’s spread over peers, not stored on any central server.
The credentials of data ownership of these persons are stored on a blockchain.
All humanitarians can read the profiles and optimize their assistance programs. They may also use this blockchain to manage these assistance programs.
The better the data, the more assistance a person can expect. This motivates the person to maintain quality data.
When national central banks will issue digital money (CBDCs), humanitarians can use Machu Picchu to distribute CBDCs directly as Cash & Voucher Assistance, and people can use it to pay the foods, the tools, their education, medical services etc.

Vision of Machu Picchu Services and Technologies

Raspberry Pi kit as delivered by LABISTS(Tm)

All Raspberry Pi starter kits are more or less the same. The one that I ordered from Labists is composed of:

A Raspberry Pi3 Model B+ board (“Model B” means “with Ethernet” while “Model A” means “without Ethernet”).
A 5V-2.5A power supply with micro-USB connector.
A 3-part black plastic enclosure.
Two heat sinks for the CPU & the DRAM.
One 32 GB micro-SD card pre-loaded with NOOBS installer (New Out-Of-Box Software) to install the OS of your choice.
One USB card reader with one USB A end and one USB C end. It is needed when you need to burn another Linux distribution not listed in the NOOBS installer, which is our case.
One HDMI cable.

Build the kit

Peel off the protective layer of the double side adhesive tape on the heat sinks and glue them on the Broadcom CPU (top side) and on the DRAM (bottom side). Press gently.

Assembling the rest of the case is straightforward. Slide the circuit board on the bottom layer of the case. Don’t assemble the rest of the case until the software is installed. It will be more practical for your installation steps below.

Advantages of doing so: First it’s easier to see the green flashing LED that signals any access to the micro-SD. Second you may often need to remove the micro-SD card to try flashing several kinds of OS.

List of installation steps

Burn the boot micro-SD card and configure it for wi-fi access.
Boot and open ssh session.
In ssh session, change hostname and password.
Initiate new ssh session with the new hostname and password.
Update and upgrade all software packages.
Prepare the mounting of the SSD.
Install IPFS and check IPFS access.

My description assumes that you use MacOS. The following blog articles will be very helpful if you are using Windows: https://desertbot.io/blog/headless-raspberry-pi-3-bplus-ssh-wifi-setup,
https://desertbot.io/blog/headless-raspberry-pi-4-external-ssd. The steps described here below have been checked one by one in the same time this article is being written.

Let’s start with the first steps to install a headless Raspbian accessible via ssh.

1. Burn the boot micro-SD card and configure it for wi-fi access

Insert the micro-SD card into the USD adapter and insert the adapter on your Mac laptop.

Launch Raspberry Pi Imager on your laptop to select which OS to flash in the micro-SD card. The video showing how to use the Imager is at https://www.youtube.com/watch?v=ntaXWS8Lk34. Unlike step 2.5 of the video, don’t specify any option. Choose “Raspberry Pi OS (other)” followed by “Raspberry Pi OS Lite (32 bit)”. Choose the storage “Mass Storage Device Media — 31.9 GB” (exact value depends on your specific micro-SD card) and flash the card. On MacOS, you need to give your administrator password.

Dialogs to select the OS to flash on the micro-SD card

Once the micro-SD card is flashed and verified, it will be “ejected” by MacOS. Remove the micro-SD card USB adapter and reinsert it back in your laptop. It appears on the Finder Desktop as a volume named boot. Place an empty file named ssh (no extension) in the root of this boot volume. It serves to signal at first boot that ssh should be enabled. It will be deleted after first boot.

Content of the micro-SD card with the 2 additional files for Wi-Fi

To create this file on MacOS, in Terminal, type touch /Volumes/boot/ssh
Create another file, wpa_supplicant.conf: type touch /Volumes/boot/wpa_supplicant.conf
Using any MacOS text editor, paste the following instructions into wpa_supplicant.conf, adjusting for your ISO 3166 alpha-2 country code, changing to your wi-fi network name (SSID) and wi-fi network password, both between quotes, like this example:

Quit the MacOS editor. Eject the USB adapter. Remove the micro-SD card. Now we can work on the Raspberry Pi.

2. Boot and open `ssh` session

Insert the micro-SD card in the RPi3, connect it to its power supply and switch power on. Wait for the green LED to stop blinking. It will take more or less 5 minutes. Check in the list of terminals on your wi-fi router that a host machine named raspberrypi has appeared.

Example how a Raspberry Pi appears on the Wi-Fi network

On your MacOS Terminal, connect by a ssh session to the RPi3. First, make sure to reset (with the command ssh-keygen) any previous parameters of ssh sessions made to raspberrypi.local. If you have never connected to such a host, MacOS will say failed. It's normal.

MBP18VTK:~ kvutien$ ssh-keygen -R raspberrypi.local     do_known_hosts: hostkeys_foreach failed: No such file or directory

If like me you have already connected by ssh to a host with that name (raspberrypi.local) in previous attempts, your MacOS will tell you that it has updated its system file named .ssh/known_hosts.

MBP18VTK:~ kvutien$ ssh-keygen -R raspberrypi.local
# Host raspberrypi.local found: line 1
/Users/kvutien/.ssh/known_hosts updated.
Original contents retained as /Users/kvutien/.ssh/known_hosts.old

Now you can ssh to the RPi3. Your Mac will tell you that it cannot establish the authenticity of this host and ask you to confirm that you still want to establish this session

MBP18VTK:~ kvutien$ ssh pi@raspberrypi.local
The authenticity of host 'raspberrypi.local (2001:7e8:ccdd:e000:f124:2430:a6d:c314)' can't be established.
ECDSA key fingerprint is SHA256:AagTtr9Bcb3VZBsWK2tWFd8CxRfWmCbGyPsA8gsPX4w.
Are you sure you want to continue connecting (yes/no)?

Answer yes and give the default password of all RPi, which is "raspberry". If you have never connected to a host with this name, here is what you will see.

pi@raspberrypi.local's password: 
Warning: Permanently added 'raspberrypi.local,2001:7e8:ccdd:e000:f124:2430:a6d:c314' (ECDSA) to the list of known hosts.

If like me you have previously connected to a host with that name, after the password is accepted you’ll have a routine ssh session feedback.

pi@raspberrypi.local's password: 
Linux raspberrypi 5.10.17-v7+ #1414 SMP Fri Apr 30 13:18:35 BST 2021 armv7lThe programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law.SSH is enabled and the default password for the 'pi' user has not been changed.
This is a security risk - please login as the 'pi' user and type 'passwd' to set a new password.

3. In ssh session, change hostname and password

Cross-check the IP address of the RPi3, as viewed from the RPi3, with the command ifconfig. We can see the IP address of the RPi3 in wlan0. In this example, we see that it's the same as seen by the wi-fi router above, 192.168.178.43. Incidentally we have confirmation, from the MAC address of the form b8:27:eb:xx:xx:xx, that it's indeed the Raspberry Pi (https://macaddress.webwat.ch/hwaddr/B8:27:EB)

pi@raspberrypi:~ $ ifconfig
eth0: flags=4099<UP,BROADCAST,MULTICAST>  mtu 1500
     ether b8:27:eb:7b:f1:b6  txqueuelen 1000  (Ethernet)
     RX packets 0  bytes 0 (0.0 B)
     RX errors 0  dropped 0  overruns 0  frame 0
     TX packets 0  bytes 0 (0.0 B)
     TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0lo: flags=73<UP,LOOPBACK,RUNNING>  mtu 65536
     inet 127.0.0.1  netmask 255.0.0.0
     inet6 ::1  prefixlen 128  scopeid 0x10<host>
     loop  txqueuelen 1000  (Local Loopback)
     RX packets 0  bytes 0 (0.0 B)
     RX errors 0  dropped 0  overruns 0  frame 0
     TX packets 0  bytes 0 (0.0 B)
     TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0wlan0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
     inet 192.168.178.43  netmask 255.255.255.0  broadcast 192.168.178.255
     inet6 fe80::d168:288d:80ee:e23c  prefixlen 64  scopeid 0x20<link>
     inet6 2001:7e8:ccdd:e000:f124:2430:a6d:c314  prefixlen 64  scopeid 0x0<global>
     ether b8:27:eb:2e:a4:e3  txqueuelen 1000  (Ethernet)
     RX packets 2359  bytes 222393 (217.1 KiB)
     RX errors 0  dropped 0  overruns 0  frame 0
     TX packets 110  bytes 16815 (16.4 KiB)
     TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

We have to change the hostname and the password. We use the command passwd to change password.

pi@raspberrypi:~ $ passwd
Changing password for pi.
Current password: 
New password: 
Retype new password: 
passwd: password updated successfully

We use sudo raspi-config to change the hostname from the default value raspberrypi to ipfs-pi, or any name of your choice. In the menu, use "Carriage Return" to select an option, or use the arrow keys to move to another option of the list. Once this done, select Finish and Reboot.

When rebooting the RPi3, the ssh session with raspberrypi.local is closed. We are back to the MacOS console.

pi@raspberrypi:~ $ sudo raspi-config
Connection to raspberrypi.local closed by remote host.
Connection to raspberrypi.local closed.
MBP18VTK:~ kvutien$

What have we achieved?

We have gone through steps 1 to 3 inclusive. At this point we have the Raspberri Pi visible on Wi-Fi as a distinct host on Internet.

We burned the boot micro-SD card and configured it for wi-fi access.
We booted the Rasperry Pi and opened the ssh session.
In ssh session, we changed hostname and password.

What remains to do now is to make it recognize the SSD (Solid State Disk) on startup and install it as an IPFS node. For this, continue with steps 4, 5, 6 and 7 in Part 2b of this article.