← Back to Wiki
Raspberry Pi / Nodes

Run a Blockchain Node on a Headless Raspberry Pi

A Raspberry Pi is enough to run a full node and support a network. You do not need a monitor or a keyboard for it, but you do have to enable SSH before the first boot. Get that wrong and you have a Pi you cannot log into.

Share on X

What to buy

A Raspberry Pi, ideally a kit. The kits include a case, heatsinks and a power adapter, which saves sourcing them separately.

An SD card. 32GB works today and a chain only grows, so take 64GB.

An SD card reader if your machine does not have one. A USB 3.0 reader writes the image faster.

Write Raspberry Pi OS Lite

Download and install the Raspberry Pi Imager. It runs on Windows, macOS and Linux.

https://www.raspberrypi.com/software/

Put the SD card in the reader and plug it in.

Windows may offer to format the card. Decline. The imager does that itself.

Open the imager and choose the OS.

Take the Lite build with no desktop environment.

A desktop on a node is spent memory and CPU you could give to the chain. You are never going to look at it.

Choose your SD card, click write, and confirm.

Enable SSH before you boot it

Current versions of the imager have a settings panel that sets a username, a password and enables SSH for you. Use it if it is there. It is the easy path.

If you are writing an image without it, do this by hand instead.

Remove the card and put it back in so the boot partition mounts.

Create an empty file in the root of that partition named ssh

No extension. No contents. The file existing is the entire signal.

Turn off hide extensions for known file types first. With that Windows default on, you make a new text document, name it ssh, and Windows quietly keeps the .txt on the end where you cannot see it. The Pi looks for a file called ssh, never finds it, and boots with SSH off. You then have a headless Pi with no way in and nothing on screen explaining why. Open File Explorer options, go to the View tab, and untick it before you rename anything.

First boot

Power the Pi off before inserting the card.

Slide the card in and connect the power.

A blinking activity light means it is reading the card.

Find it on the network

Log into your router and look at connected devices.

An IP scanner on your desktop works just as well.

Note the address.

Give the Pi a DHCP reservation while you are in the router. A node whose address moves is a node you have to go find again every time the lease expires.

Open the port while you are in the router

A node that cannot accept inbound connections is only half participating.

Forward the port your chain uses to the Pi's address.

Ravencoin uses 8767, for example. Check the port for the chain you are running.

The menu is called port forwarding on most routers and NAT on others.

Log in

Connect with PuTTY on Windows, or with ssh from a terminal on macOS or Linux.

ssh [email protected]

Use whichever username you set in the imager.

Older images shipped with a default account and a default password and expected you to change it. Newer ones make you set one at write time, which is the better behaviour.

Do not leave a default password on it just because there is no wallet on the box. A node with nothing valuable on it is still a Linux machine on your network with a port open to the internet. That is worth something to somebody regardless of what it stores. Set a real password, and put a key on it if you are comfortable doing so.

Then install the node software

Update the system first with command sudo apt update && sudo apt upgrade

Get the node build from the project itself rather than a link you found in a comment. Most chains publish an ARM build for exactly this.

Some communities maintain a setup script that does the whole install. They save real time, and you are handing root on that box to whoever wrote it, so read it before you run it.

Expect the initial sync to take a while. That part is the chain's size, not the Pi being slow.