Running an ION node on your Raspberry 4

ION V1 was announced today.

ION is used in a decentralized identity network to be able to help resolve for example decentralized identifiers and find their public keys. This is one of the core differences with a traditional Identity Provider where you always need to go to the well-known endpoint to retrieve the location of the public keys and download the public keys there to see if the signatures of the tokens are correct. This blog post isn’t about explaining how ION works. There are a few good spots to go for that:

It’s possible to run your own ION node, this post is about how to get it installed on a Raspberry Pi. Yes that’s right. ION nodes can run on something as lightweight as an RPI4. The future is even brighter when the promised updates on ION will introduce a light mode which makes it even easier to run a node yourself.

Why would you run your own node? Beside it’s just fun to experiment, you can look at running an ION node as running a local DNS server but for decentralized identifiers. Resolving DIDs will be faster if you do it against a node running close. 2nd you help building the ION network. Since it’s based on peer 2 peer file system (IPFS) more nodes make it faster and more robust. 3rd, if you don’t want to trust or rely on anybody, you can run your own node. Trust code and math and you can be sure the information resolved is correct and validating DIDs from anybody/anything is happening correctly.

But as a first step to take control you can run your own node. You would expect these kind of services to be complex to run and need their own dedicated hardware. I found out it runs on a Raspberry just fine. There are some gotchas to run the software on a Raspberry compared to a regular Ubuntu AMD64 environment. The instructions for those are found here. I recently pushed a PR with instructions how to run the node in Docker Containers. Currently the ION infrastructure is not as simple as it will be. It needs a bit of ‘step by step’ setting up and starting. This will be easier in the future, but for now it needs a bit of hand holding.

There are few steps we need to take:

  1. Install an OS. I have chosen Ubuntu 64 bits
  2. Install docker
  3. Install npm and node
  4. run the install script to create all the docker containers and run the ION node

prepare hardware

I ordered a Raspberry 4 8GB from Amazon, and I attached an SSD hard drive to it. There will be a lot of write transactions, especially during initial setup so you need something which can survive these kind of writes. Fortunately a Raspberry can now boot from an SSD.

I used a 500GB SSD I had in my drawer.

Install Ubuntu 64 bits on RPI

Fortunately the RPI can now boot from SSD. If you have an old one you might need to upgrade the firmware. I just downloaded the 64 bits verion of Ubuntu from the download page. I run the 64 bits version since MongoDB needs 64 bits. You can find instructions how to install Ubuntu on a Raspberry Pi here After you successfully installed the OS we can continue to the next step.

Install docker

I installed docker by following the instructions here

I do like to use the Portainer dashboard for easy managing and watching docker running on my RPI.

Oh, and you should probably install docker-compose:
sudo apt-get install docker-compose

Install ION

Now to the fun part. Install ION and run all the different containers. We need to change some of the files since the default docker compose files doesn’t work on ARM64, the IPFS container we need to run doesn’t exist for ARM64 builds yet.

But first we need to get the ION repo, and install nodejs and npm.

Clone the ION repository:
Git clone

Let’s create a directory where we going to store all data. This will contain the bitcoin database, IPFS data and mongodb database.
mkdir iondata

Install node and NPM:
sudo apt install nodejs
sudo apt install npm

build the ION software:
cd ion
npm install
npm run build

Run the setup script

Now we need to change the docker file:
cd docker

Modify the docker-compose.yml file and change the IPFS image to mhoekstra/go-ipfs:v0.7.0 (I created this image since the IPFS team doesn’t create a docker image for ARM64 yet, they are looking for help)

Change the permissions on the script so you can execute:
chmod +x

Run the script: `./’

use these directories: /home/ubuntu/iondata/bitcoin /home/ubuntu/iondata/mongo /home/ubuntu/iondata/ifps

This will create the correct docker images, docker volumes, create the config files and modify the settings for all containers. 5 different containers will be created and need to get started in order.

The first takes the most time, sometimes up to 48 hours. This is the bitcoin-core-mainnet container and this will download the entire bitcoin database. This is needed to 100% guarantee the latest blocks are correct. In the future this will be optimized and you will be able to prune.

The mongodb and IPFS container will be created

Then the ion-bitcoin-mainnet container will be started. This will read all the blocks from the bitcoin-core-mainnet instance and will look for ION/Sidetree transactions.

Once that’s done (this will take some time as well) the last node will be started, the ion-core-mainnet node. This node will listen on port 3000.

An easy check if it’s running is to go to http://ipaddress:3000/version

To check if you can resolve a DID: http://ipaddress:3000/identifiers/identifiers/did:ion:EiClkZMDxPKqC9c-umQfTkR8vvZ9JPhl_xLDI9Nfk38w5w

Happy resolving!