This tutorial walks you through installing Bitcoin Core v0.13.2, or possibly newer, on a Raspberry Pi 2 or 3 using either Raspbian (Raspbian Jessie January 2017 Release) or Ubuntu Mate 16.04, or possibly newer, as your operating system. Options are given to install the GUI and wallet, or not. Options are given to store the blockchain on an external USB flash drive (or hard drive), or on a large microSD card with the OS.
Other than one instance where apt-get must be used on Raspbian, we’ll be using apt, a new package manager poised to replace apt-get. It simplifies and merges multiple commands, is more efficient, and is intended to be more pleasant and readable for users.
Hardware for Node
- Raspberry Pi 2 or 3
- Case for Raspberry Pi B+ Form Factor (Optional)
- Heatsinks for Raspberry Pi (Optional)
- Power Supply (Micro-USB, 5V, 1.8A for the Raspberry Pi 2 or 2.5A for the Raspberry Pi 3)
- Ethernet Cable or USB Wi-Fi Adapter (Only Required if Using a Raspberry Pi 2, Raspberry Pi 3 Includes Wi-Fi)
- 8GB MicroSD card (Class 10) with USB Storage, or 128GB Minimum MicroSD Card
- USB Flash drive or USB External Hard Drive (128GB Minimum, USB 2.0 or Higher)
Hardware for Set Up
- HDMI Cable
- Monitor with HDMI, or Monitor and HDMI Adapter
- USB Keyboard and Mouse
- Router or Modem with Internet Connection
- Separate PC with MicroSD Card Reader
Choosing the OS
Raspbian is a more simple and less resource intensive OS compared to Ubuntu Mate, although more or less as capable, and you can easily set it up to boot to the command line interface rather than the full desktop environment.
Ubuntu Mate is great for people familiar with Ubuntu and it offers a more feature full and customizable desktop environment when compared to Raspbian. However, it does take slightly longer to set up and uses more resources.
Setting Up the OS
Install Raspbian or Ubuntu Mate on your flash card using a separate PC. Once the OS has been written to the MicroSD card, insert it into your Raspberry Pi, connect the monitor, keyboard, and mouse, and, finally, plug the power supply in.
Once at the desktop, press the CTRL + ALT + T keys to open a terminal window or, alternatively, click on the terminal icon on the menu bar. At first, the keyboard was initially set to UK layout and some keys didn’t work as expected. You can change it to United States > English (US), or any other available layout, in the settings.
You’ll either need an ethernet cable plugged into the Raspberry Pi or, if using a Raspberry Pi 3 or USB Wi-Fi adapter, you’ll need to enter your Wi-Fi details. Once you’re connected to the internet, you can run the following commands to install git, a popular version control system which we’ll use when installing Bitcoin Core, and available updates.
sudo apt install git sudo apt update sudo apt full-upgrade sudo apt-get autoremove
When you first boot Ubuntu Mate on your Raspberry Pi, you’ll be walked through the configuration process before being able to use the desktop interface. Select your settings, choose a username and password, and wait for the installation to finish. Once at the desktop, press the CTRL + ALT + T keys to open a terminal window or, alternatively, go to Applications > System Tools > MATE Terminal.
Once you have your terminal window opened, you can type the following command to check that the file system is using all of your available space.
If the size of /dev/root doesn’t match your micro SD card, you’ll need to re-size the file system. You can do so by going to System > Welcome, clicking the Raspberry Pi Information button, and following the instructions listed under “resizing the file system.” This Welcome page will also open automatically when you first get to the desktop and every time you reboot the system, until you uncheck the box “Open Welcome when I log on.” You’ll need to reboot after resizing the file system for the changes to take effect. After rebooting, you can check that the re-size was successful by running the df -h command again.
As with Raspbian, you’ll either need an ethernet cable plugged into the Raspberry Pi or, if using a Raspberry Pi 3 or USB Wi-Fi adapter, you’ll need to enter your Wi-Fi details. Once you’re connected to the internet, you can run the following commands to install git, a popular version control system which we’ll use when installing Bitcoin Core, and available updates.
sudo apt install git sudo apt update sudo apt full-upgrade sudo apt autoremove
Making a Swap File
Due to the Raspberry Pi only having 1GB of RAM, we need to make a 1GB swap file, otherwise building Bitcoin Core will fail as the available memory is exhausted. The steps are slightly different between Raspbian and Ubuntu Mate, so follow the commands for the OS you’re using.
First, we’ll edit the file “/etc/dphys-swapfile”:
sudo nano /etc/dphys-swapfile
Replace the text “CONF_SWAPSIZE=100” with “CONF_SWAPSIZE=1024”, then save the changes by typing Ctrl + O and exit nano by typing Ctrl + X.
Next, you will need to stop and start the service that manages the swap file on Raspbian:
sudo /etc/init.d/dphys-swapfile stop sudo /etc/init.d/dphys-swapfile start
You can verify the amount of swap by entering the following command:
Next, we’ll create the swap file using the following command:
sudo fallocate -l 1G /swapfile
Last, we’ll set the file permissions, mark the file as swap space, and enable the swap file using the following commands.
sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile
You can verify that the swap is available by entering:
sudo swapon --show
A Note on MicroSD Card Wear
After you’ve finished setting up Bitcoin Core as described in this tutorial, you may choose to disable swap to protect your MicroSD card from wear caused by excessive writes. MicroSD cards have a limited number of writes before failure, and while it might not have much of an effect on your MicroSD card, it should no longer be necessary after Bitcoin Core has been built. You can disable it if you choose to.
From this point on there shouldn’t be any differences between Raspbian and Ubuntu Mate. Enter the following command to install the required dependencies for Bitcoin Core.
sudo apt install autoconf build-essential libboost-chrono-dev libboost-filesystem-dev libboost-program-options-dev libboost-system-dev libboost-test-dev libboost-thread-dev libevent-dev libminiupnpc-dev libssl-dev libtool libzmq3-dev
If you would like to use the GUI wallet, enter the following command to install the required dependencies. If you don’t install these dependencies, the GUI wallet will be unavailable.
sudo apt install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler libqrencode-dev
Enter the following commands to create a new directory named “bin” and set it as your current directory.
mkdir ~/bin cd ~/bin
Enter the following command to download the latest version of Bitcoin Core from the 0.13 branch. In the future, you may want to update this command if newer branches have been released.
git clone -b 0.13 https://github.com/bitcoin/bitcoin.git
Installing Berkeley DB 4.8
You don’t need to install Berkeley DB 4.8 if you don’t want to use the Bitcoin Core wallet functionality, but you’ll have to modify a command as explained later in the “Installing Bitcoin Core” part of this tutorial. If you want to use the wallet functionality, continue below, otherwise you may skip to “Installing Bitcoin Core” and proceed from there.
Enter the following commands to create a new directory named “berkeleydb.4.8” inside of the “bitcoin” directory that the previous git clone command created. This will be used to install Berkeley DB 4.8, a required dependency for Bitcoin Core.
Enter the following commands to download Berkeley DB 4.8 from Oracle and verify that it has not been tampered with.
wget 'http://download.oracle.com/berkeley-db/db-4.8.30.NC.tar.gz' echo '12edc0df75bf9abd7f82f821795bcee50f42cb2e5f76a6a281b85732798364ef db-4.8.30.NC.tar.gz' | sha256sum -c
The previous echo command should output “db-4.8.30.NC.tar.gz: OK” if the file was verified successfully. If you get a different output, try repeating the wget and echo commands.
Enter the following commands to unpack the file and set the new directory as your current directory.
tar -xzvf db-4.8.30.NC.tar.gz cd db-4.8.30.NC/build_unix/
You’ll need to replace “USER” in the commands below with your username, which you can find by entering the following command:
Once you know what your username is, you’re ready to modify and enter the following commands to install Berkeley DB 4.8. Remember to replace “USER” in the configure command with your actual username.
../dist/configure --enable-cxx --disable-shared --with-pic --prefix=/home/USER/bin/bitcoin/berkeleydb.4.8 make sudo make install
Installing Bitcoin Core
Now you’re ready to modify and enter the following commands to install Bitcoin Core. You can modify the configure command using the following options.
If you don’t want to use the GUI, remove “–with-gui”, if you don’t want to use the Bitcoin Core wallet functionality add “–disable-wallet”, if you don’t want to use UPnP, which automatically tries to open port 8333 on your router for incoming Bitcoin connections, then remove ‘–enable-upnp-default’, but it’s recommend to enable UPnP.
This process will take some time, so just let it run until it’s finished. Remember to replace “USER” in the configure command with your actual username.
cd ~/bin/bitcoin/ ./autogen.sh ./configure LDFLAGS="-L/home/USER/bin/bitcoin/berkeleydb.4.8/lib/" CPPFLAGS="-I/home/USER/bin/bitcoin/berkeleydb.4.8/include/" --enable-upnp-default --with-gui make sudo make install
Choose Where to Store the Bitcoin Blockchain
If you have a big enough MicroSD card and want to store the Bitcoin blockchain on it, you don’t need to take any extra steps. A directory named “~/.bitcoin” will be automatically created for you and all of the blockchain data, as well as the “bitcoin.conf” configuration file will be stored in that directory.
If you’re storing the blockchain on an external USB flash drive or external USB hard drive, then proceed with the following steps.
Make sure your external storage is empty and is formatted in a format that works natively with Linux, such as FAT32. You can check what format your external storage is formatted in on your PC that you used to write your Raspberry Pi OS to your MicroSD card. If it isn’t empty or is in a format that won’t work with Linux, then format it as FAT32 and connect it to your Raspberry Pi.
Enter the following command to create a new directory called “/bitcoinData” to use as the mount point for your external storage:
Enter the following command to find your external storage device:
You should see a listing matching the size of your external storage and its type should be “vfat” if your external storage is formatted as FAT32. You need to determine what the /dev/sdX is. It could be sda1, sdb1, or something similar, but it will most likely be sda1. Once you have that, enter the following command to edit the “/etc/fstab” file.
sudo nano /etc/fstab
Replace “sdX” with the correct value and replace the three occurrences of “USER” with your username as in previous steps. This will automatically mount the USB drive to “~/bitcoinData” on boot.
/dev/sdX /home/USER/bitcoinData vfat uid=USER,gid=USER,umask=0022,sync,auto,nosuid,rw,nouser 0 0
Save the changes by typing Ctrl + O, exit nano by typing Ctrl + X, and reboot your Raspberry Pi.
Choosing Your Blockchain Source and Using Bitcoin Core
You can either copy the blockchain from a trusted computer that has already downloaded it, or you can do a fresh sync from the Raspberry Pi itself. However, be aware that freshly syncing the blockchain on the Raspberry Pi takes weeks.
Copying a Trusted Copy of the Blockchain
If you are copying the Bitcoin blockchain from another computer, copy the “blocks” and the “chainstate” directories to either “~/.bitcoin” or “~/bitcoinData” depending on whether you decided to use external storage or not.
If you’re using external storage to store the blockchain, then start the Bitcoin node using the following command, remembering to replace “USER” with your actual username.
bitcoind -datadir=/home/USER/bitcoinData -daemon
If you’re storing the blockchain on your MicroSD card, then use the following command instead and it will use the default data directory, “~/.bitcoin”.
Downloading a New Copy of the Blockchain
If you’re downloading a new copy of the blockchain, you’ll have to wait while it syncs. It takes about fifteen days to sync up to block 450,000 on a Raspberry Pi 3. You’ll need to have a 1GB swap file enabled while it syncs, and you’ll need to start the Bitcoin node using one of the following commands to enable it to use additional memory. Choose the appropriate command based on whether you’re storing the blockchain on external storage or not and replace “USER” with your actual username if required.
bitcoind -datadir=/home/USER/bitcoinData -dbcache=2048 -daemon
bitcoind -dbcache=2048 -daemon
Alternatively, you can set the dbcache value in the “bitcoin.conf” file and not include the “-dbcache=2048” argument in the command.
You can check the progress by using the following command to get the current block count once you’ve started the Bitcoin node:
You can check the status of your Bitcoin full node by entering the following command:
Congratulations, you should now have a working Bitcoin full node set up on your Raspberry Pi!