This document guides you step by step on how to run BTCPay Server on a Raspberry Pi 4. See here the Raspberry Pi 3 instructions
The newly released Raspberry Pi 4 is currently the best low-cost single-board computer available. You can use a Raspberry Pi 4 to run your BTCPay Server at home for around $150 worth of parts, described below.
- Raspberry Pi 4 with 4GB RAM ($55)
- Sandisk 16GB SD Card ($5)
Don’t settle for only 1GB or 2GB of RAM. The 4GB RAM version is harder to find than the other versions, but you absolutely want that 4GB of RAM for a few extra bucks, and it’s totally worth spending a few extra minutes searching on the Internet to find a vendor that has the 4GB RAM version in stock. You’ll also need an SD card reader if you don’t already have one.
- Official Raspberry Pi 4 USB-C Power Adapter 5.1V/3A for US ($10)
- Official Raspberry Pi 4 USB-C Power Adapter 5.1V/3A for EU ($10)
- Official Raspberry Pi 4 USB-C Power Adapter 5.1V/3A for AU ($10)
Don’t waste your time with random Chinese power adapters from Amazon, or expect that the existing ones you have at home are going to work fine. The Raspberry Pi 4 has issues with unofficial adapters, and for only $10 it’s better to just get an official adapter instead of learning this the hard way.
- Pimoroni Fan Shim ($10)
Strictly speaking, you don’t actually need a cooling solution, but you certainly want a cooling solution, because once the Raspberry PI core temperature reaches 70C, it will throttle the CPU down to avoid burning itself up.
- Flirc Heatsink Case ($12)
- Pimoroni Pibow Coupé 4 ($9)
Of course, using a case is totally optional, but we recommend one to protect your Raspberry Pi over the long-term and prevent random dust from shorting out the pins.
- Samsung 500GB SSD ($75)
The 500GB SSD allows you to keep a full copy of the Bitcoin blockchain, until it grows past 500GB sometime in 2022. At that time, you’ll either have to enable pruning on your Bitcoin node, or upgrade to a 1TB SSD, which will presumably be cheaper then, probably even less than $75. You can also use BTCPay without a full copy of the Bitcoin blockchain.
- Display ($100)
- Important: Attach a heatsink to the CPU! 🔥🔥🔥
- Connect the SSD to one of the blue colored USB 3 ports
- Prepare the USB Power Adapter but don’t plug it in yet
Start by downloading Raspbian Linux to your existing computer. The “Lite” distribution is fine for BTCPay setup, but if you want to use your Raspberry Pi for other things, you might want the full image.
Assuming you’re running macOS, first you need to identify which device is your SD card. Plug your SD card into your SD card reader and type:
sudo -sdiskutil listYou’ll see a list of disks like this:
Here’s where your computer might be different from the above and you need to be careful. From the above list of disks on my computer, I can identify disk0 and disk1 are my mac’s internal hard disks. But that 32GB “external” and “physical” disk2 is the same size as my SD card and has some Windows partition on it, so I can identify my SD card is disk2.
🚨 WARNING: You need to correctly identify the drive number of your SD card, and modify the following commands before typing them, or you could accidentally erase your computer’s hard drive instead. 🚨
Don’t copy and paste the following, you need to replace the 3 instances of diskX in these commands with your actual drive ID. For me this was disk2,but it might be different for you. The following commands will erase the SD card, and then write the Raspbian image to the SD card, so be careful not to mess up these commands.
diskutil unmountDisk diskX
dd if=/dev/zero of=/dev/rdiskX bs=4m count=100
dd if=/path/to/raspbian.img of=/dev/rdiskX bs=4m🚨 WARNING: If you incorrectly flash the wrong drive, you could erase your computer’s hard drive instead of the SD card. Double check you have the disk ID correct so you don’t accidentally erase your data. 🚨
If all went well, you should see the commands return something like this:
Next, enable SSH at bootup so you can remotely login, and finally eject the SD card so you can move it to the Raspberry Pi. The new SD card’s boot partition should automatically be mounted on /Volumes/boot
touch /Volumes/boot/ssh
diskutil eject disk2
After inserting the SD card into the Raspberry Pi, go ahead and connect the power and ethernet, and optionally the display and keyboard if you have those. It should boot up and get an IP address using DHCP. You can try searching for it with ping raspberrypi.local on your desktop PC, but if that doesn’t work you will need to login to your router to find its IP address.
The IP address that my Raspberry Pi got was 192.168.1.5 so I SSH’d to that
ssh 192.168.1.5 -l pi
The default password for the “pi” user is “raspberry”. After SSH’ing in, the first thing I want to do is check the device’s CPU temperature to make sure the cooling system are working correctly:
sudo -svcgencmd measure_tempNext, let’s change the password for the “pi” user.
passwd piI also recommend to disable swap to prevent burning out your SD card.
dphys-swapfile swapoff
dphys-swapfile uninstall
update-rc.d dphys-swapfile remove
systemctl disable dphys-swapfile
Partition your SSD
fdisk /dev/sda
# type 'p' to list existing partitions
# type 'd' to delete currently selected partitions
# type 'n' to create a new partition
# type 'w' to write the new partition table and exit fdiskFormat the new partition on your SSD
mkfs.ext4 /dev/sda1Configure the SSD partition to auto-mount at bootup
mkfs.ext4 /dev/sda1
mkdir /mnt/usb
UUID="$(sudo blkid -s UUID -o value /dev/sda1)"
echo "UUID=$UUID /mnt/usb ext4 defaults,noatime,nofail 0" | sudo tee -a /etc/fstab
mount -aWhile you’re editing /etc/fstab add a RAM filesystem for logs (optional). This is also to prevent burning out your SD card too quickly.
none /var/log tmpfs size=10M,noatime 00Mount the SSD partition and create a symlink for docker to use the SSD
mkdir /mnt/usb/docker
ln -s /mnt/usb/docker /var/lib/dockerUpgrade your OS packages to latest
apt update && apt upgrade -y && apt autoremoveInstall a firewall and allow SSH, HTTP, HTTPS, Bitcoin, and Lightning
apt install -y ufw
ufw default deny incoming
ufw default allow outgoingThis command allows SSH connections from internal networks only:
ufw allow from 10.0.0.0/8 to any port 22 proto tcp
ufw allow from 172.16.0.0/12 to any port 22 proto tcp
ufw allow from 192.168.0.0/16 to any port 22 proto tcp
ufw allow from 169.254.0.0/16 to any port 22 proto tcp
ufw allow from fc00::/7 to any port 22 proto tcp
ufw allow from fe80::/10 to any port 22 proto tcp
ufw allow from ff00::/8 to any port 22 proto tcpThese ports need to be accessible from anywhere (The default subnet is 'any' unless you specify one):
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 8333/tcp
ufw allow 9735/tcpVerify your configuration:
sudo ufw statusEnable your firewall:
ufw enableDownload BTCPay Server from GitHub
apt install -y fail2ban git
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker
sudo su -
cd ~pi/btcpayserver-docker/Configure BTCPay by setting some environment variables:
export BTCPAY_HOST="raspberrypi.local"
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_LIGHTNING="lnd"
export BTCPAYGEN_REVERSEPROXY="nginx"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-more-memory"
export BTCPAYGEN_EXCLUDE_FRAGMENTS="opt-add-tor"
export BTCPAY_ENABLE_SSH=trueIf you want to use multiple hostnames, add them via the optional BTCPAY_ADDITIONAL_HOSTS variable:
export BTCPAY_ADDITIONAL_HOSTS="btcpay.YourDomain.com,btcpay.local"In case you want to restrict access to your local network only, please note that you need to use a .local domain.
Run the BTCPay installation:
. ./btcpay-setup.sh -iIt should be up and running within a few minutes. Try opening http://raspberrypi.local in your web browser. If everything is correct, you will see BTCPay Server front page.
Now, you just need to wait a day or so for the Bitcoin blockchain to sync and full verify. The bottom of the BTCPay Server web GUI will show a pop-up dialog box to monitor the progress.