Raspberry Pi Headless IPFS Setup

This article covers how to setup IPFS on a Raspberry Pi.

If you are using a desktop installation, you can just open up a command line (terminal) window and skip the first few steps.

A note about terminology

  • Uppercase IPFS refers to the project: InterPlanetary File System
  • Lowercase ipfs stands for the command line tool

Step 1. Setup a lite image

For this article I started with a new Raspberry Pi lite image using these instructions:

Step 2. Login to the pi over ssh

Because my pi is called pi4, I login over ssh like this:

ssh pi@pi4.local

Be sure to adjust the instructions above for the host name that you are using.

Step 3. Install git

To make installation easier, I'm going to show you how to download and install a script using git.

To see if you already have git installed, run this command:

git version

If you get an error, then you need to install git with this command:

sudo apt install git

Step 4. Clone the install script

After trying several ways to install IPFS on a Raspberry Pi, I found this install script the most reliable:

git clone https://github.com/claudiobizzotto/ipfs-rpi.git

I have no control over that third party script. So if it goes away or is changed drastically I forked a copy at:

If you know how to fork projects using git, I would suggest that you also fork a copy as well. That way you know you will always have a copy to use.

Step 5. Run the install script

When you cloned the script it should have put it into a folder that matches the name of the git repo (ipfs-rpi).

Change to that directory and run the install script by doing the following:

cd ipfs-rpi/
./install

You should see a line to cat a readme file using the ipfs command line tool.

Copy and paste the command into the command line and run it:

ipfs cat /ipfs/QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc/readme

The long string of numbers and letters is the unique address of the readme file on IPFS. It is referred to as the content identifier or CID for short. If the file changed, the CID may have changed. So be sure to use the command and CID echoed on your screen. I just showed you what I received as an example. If the version of the ipfs command line tool has changed, it's likely the CID above has changed.

Step 6. Check the version

Next you should check the version of the ipfs command line tool that you are running:

ipfs version

You should just see the version number echoed to the screen, with no errors.

Step 7. Verify that the IPFS service is running

I have found that even if you can run basic ipfs commands, that doesn't mean that the ipfs service (daemon) is running.

To verify that the service is running, run this command:

ipfs swarm peers

A long list of peers should be echoed to the screen.

If you get errors, see some of the references at the end of this document.

Step 8. Confirm after reboot

To confirm that the IPFS service will still run after reboot, do the following:

sudo reboot

Give your Raspberry Pi a minute or two to reboot.

Connect again (substitute your user and hostname):

ssh pi@pi4.local

To verify that the service is still running after reboot, run this command:

ipfs swarm peers

If you see a long list of peers and no errors, you should be good to go.

Step 9. Add a file to IPFS

First, create a new file - but change the text in the quoted string below so that your message is unique:

echo "Hello from a pi" > ~/test.txt

Then add it to IPFS using this command:

ipfs add ~/test.txt

You should see a response like this:

added QmRtm2vzXs9ZUWD1HtYjMTbKnEzm6jNNWXagMBCSU7BdF5 test.txt
 16 B / 16 B [====...===] 100.00%

The CID returned is for the file that I added - yours will be different.

To verify that the file was added, paste the CID into a command like this (subsituting your CID for mine):

ipfs cat /ipfs/QmRtm2vzXs9ZUWD1HtYjMTbKnEzm6jNNWXagMBCSU7BdF5

That just echoes the contents to the screen. To save a copy locally, redirect the output into a new file, like this::

ipfs cat /ipfs/QmRtm2vzXs9ZUWD1HtYjMTbKnEzm6jNNWXagMBCSU7BdF5 > ~/mycopy.txt

To verify that the copy was created locally, run this command:

cat ~/mycopy.txt

Step 10. Pin the file

Files added to IPFS may be garbage collected (deleted), unless at least one node "pins" it.

To pin the file you added to IPFS, run this command (substituting your files CID address):

ipfs pin add QmRtm2vzXs9ZUWD1HtYjMTbKnEzm6jNNWXagMBCSU7BdF5

You should get back a reponse like this:

pinned QmRtm2vzXs9ZUWD1HtYjMTbKnEzm6jNNWXagMBCSU7BdF5 recursively

Step 11. Verify that the file is available globally

There are several ways to verify the file exists outside the Raspberry Pi.

Use the Cloudflare IPFS Gateway

To use the Cloudflare IPFS Gateway to see your file, use the URL below (substitute the CID for your file):

https://cloudflare-ipfs.com/ipfs/QmRtm2vzXs9ZUWD1HtYjMTbKnEzm6jNNWXagMBCSU7BdF5

I tested the above using Chrome.

Use the Brave browser

Another way to access a file through IPFS is with the Brave browser.

The Brave browser is based on Chrome and supports the ipfs protocol in the address bar.

You can download the Brave browser from here:

I tested it using the Brave browser running on my Mac.

In the Brave browser enter this address (subsituting my CID for yours):

ipfs://QmRtm2vzXs9ZUWD1HtYjMTbKnEzm6jNNWXagMBCSU7BdF5

It may take a moment, but then you should see the file contents echoed to the browser.

Note that that only seems to work in the desktop Brave browser. The iOS version redirects the input to Google Search.

Use the Pinata service

Yet even another way to see the file is using the Pinata service. With that service you can also upload and pin files using the cloud instead of a Raspberry Pi.

Because your Raspberry Pi is the only node that has pinned the file, there is no guarantee that when your node is offline that the file will still be available. If you'd like the file to be available even when your Raspberry Pi is down, use a service like Pinata to pin it.

Use the IPFS Desktop

In addition to the services above, you can run IPFS desktop on your local machine to access the files. You can even use the desktop to add files to trade back and forth with your Raspberry Pi.

Note that anyone who knows the CID of these files can access them. So don't send anything private.

Use the Chrome IPFS extension

Note that the Chrome IPFS extension below needs the IPFS desktop running to work!

Troubleshooting

  • If you get errors about resources not being found, make sure that you copied the entire CID address of a file
    • With such long strings it's common to accidentally copy only part of the string
    • An easy check is to note the first few and last few alphanumeric characters of the CID and make sure that they match
  • If you are getting other errors, please refer to the documentation references at the end of this article.

Conclusion

In this article you learned how to:

  • Install IPFS on a Raspberry Pi
  • Install git to clone a repo
  • Add files to IPFS
  • Download files from IPFS
  • Pin files to IPFS
  • Several ways to share and access files on IPFS

Related Articles

References

  • https://ipfs.io/ - [1]
  • How to Build an NFT IPFS Wallet for Your Collection - [2]
  • How to Create NFTs with IPFS and Digital Art - [3]
  • IPFS Doc: Command Line - [4]
  • IPFS Doc: Take your node online - [5]
  • github.com/claudiobizzotto/ipfs-rpi - [6]
  • github.com/lanzafame/ipfs-cluster-rpi - [7]