Running SubQuery on a Raspberry Pi

This post is a step-by-step guide to my experience running a SubQuery project on a Raspberry Pi 4 with 8GiB RAM. Can the diminutive server-in-a-matchbox pack enough punch to index the Ethereum Gravatar SubQuery project? Read on to find out!

First, a word on OS selection. It’s possible to run Ubuntu (Desktop and Server) on a Pi but for the purposes of this experiment we are going with Raspbian as it’s the default OS for a Pi and represents a bigger challenge. In my experience, if something runs on Raspbian, it will run fine on ARM Ubuntu too. The same can’t always be said the other way round.

I used the Raspberry Pi Imaging Utility to load Raspbian onto a fresh memory card. For this test I had a 512GiB one waiting for another project which got volunteered. I’ve used the imager tool many times before so installation was a breeze. The freshly setup SD card was slapped in the Pi and it was fired up destined to become a PiOneer for SubQuery (geddit?)


SSH, network access and security were setup as part of the imaging process so I was soon logged in. Let’s roll up our sleeves and start by updating everything:

sudo apt update
sudo apt upgrade

These next few steps are documented in greater detail in the fantastic SubQuery quick start documentation. To use the SubQuery CLI we will need to install the node.js JavaScript runtime environment:

curl -fsSL | sudo -E bash -
sudo apt install nodejs

To verify this step has worked, check the version:

node --version

If all is well, we should see a version number echoed back to you. Something like this:


We also need the Yarn package manager but now npm is installed it’s as easy as:

sudo npm install --global yarn

Next, we need Docker setup. The official documentation recommends using the convenience script to install Docker on a Pi:

curl -fsSL -o
sudo sh

OK, so now we have Docker, we will use npm to install the SubQuery CLI:

sudo npm install --global @subql/cli

Running subql help will ensure everything is working up to this point.

Now the magic happens; we will create a SubQuery project:

subql init

We are asked a few questions which we’ll answer in this way:


The important parts are to give the project a meaningful name and select Ethereum as the network. The rest of the values can be left as defaults. Now we have the starter project pulled from the SubQuery GitHub in the folder raspbian-ethereum. We ask yarn to install dependencies like this:

cd raspbian-ethereum
yarn install

One thing to note is that the starter project targets the older version of Docker Compose. Thie means it tries to run docker-compose to invoke the command whereas we have installed the latest version which needs to use docker compose to do the same. To fix this, open the package.json file and replace all instances:

    "start:docker": "docker-compose pull && docker-compose up --remove-orphans",
    "dev": "subql codegen && subql build && docker-compose pull && docker-compose up --remove-orphans",


    "start:docker": "docker compose pull && docker compose up --remove-orphans",
    "dev": "subql codegen && subql build && docker compose pull && docker compose up --remove-orphans",

At this point it is time to switch over to the quick start documentation for the Ethereum Gravatar project. Another example of the great developer experience the SubQuery team have put together for us. Follow the instructions within step-by-step and in two shakes we need to run sudo yarn start:docker and are indexing the Gravatar project on a Pi.


Is the Pi melting from the effort? Far from it:

After a short while we reach chainhead:

And we can query the data in the playground:

So, in conclusion, can the Raspberry Pi run a SubQuery project? You bet your sweet bippy it can! It’s a simple and inexpensive way to get started developing your own projects. Would I use it to run an indexer? I think I’d take advantage of the wealth of infrastructure and resilience the SubQuery Network provides rather than bake a Pi into delivering an end user experience. Thanks for reading!

Big Jim | counterpoint

If you enjoyed this post, please consider delegating to our indexer. Find me on the SubQuery Discord if you have any questions.


Thanks for this Jim, good work! If I get tokens else, I will delegate to you :+1:

1 Like

This is excellent work @jim-counter !

1 Like