# Raspberry Pi 4 Deployment

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 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.

# Quickstart

Already have a Raspberry Pi 4B with the following specs?

- 4GB memory
- 1TB USB 3.0 SSD
- 16GB or greater SD card   

Download the latest 64 Bit RaspiOS (opens new window).

  • Select the most recent directory and download the zip file.
  • Flash the image to your SD card.
  • If you don't have a keyboard and monitor make sure you enable SSH by creating empty file named "ssh" on the "boot" folder of the SD card.

Login to the RPI (the default username is "pi" and the default password is "raspberry") and run the following commands. If you don't have a keyboard and LCD screen use Putty (opens new window) to connect via SSH.

Change your password.


For LND Full Node - IBD takes approximately 36 hours after initial install.

sudo su -
wget -O btcpayserver-install-lnd.sh https://raw.githubusercontent.com/btcpayserver/btcpayserver-doc/master/docs/Deployment/btcpayserver-lnd-rpi4-install.md
chmod +x btcpayserver-install-lnd.sh
. btcpayserver-install-lnd.sh

For C-Lightning Full Node - IBD takes approximately 36 hours after initial install.

sudo su -
wget -O btcpayserver-install-clightning.sh https://raw.githubusercontent.com/btcpayserver/btcpayserver-doc/master/docs/Deployment/btcpayserver-clightning-rpi4-install.md
chmod +x btcpayserver-install-clightning.sh
. btcpayserver-install-clightning.sh

After initial setup is complete open a browser on another computer and go to btcpay.local

# Detailed Step by Step Instructions.

# Required Hardware

# Raspberry Pi 4

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.

# Power Adapters and USB-C Cable

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.

# Cooling options: Passive vs Active vs Passive+Active

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.

# Case options: Naked vs. Protection

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.

# Data storage options: SSD vs USB memory vs SD card

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 options: Display or Headless

  • Display ($100)

# Assembling the Raspberry Pi 4 components

  • 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
RPI4 Components

# Install Linux on the Raspberry Pi

Start by downloading the latest 64 Bit RaspiOS (opens new window): Select the most recent directory and download the zip file to your existing computer. The “Lite” distribution is fine for BTCPay setup.

# Flash your SD card with the Raspberry Pi OS for Linux

  • Extract the downloaded Zip file
  • Download the latest version of balenaEtcher (opens new window) and install it.
  • Connect an SD card reader with the SD card inside.
  • Open balenaEtcher and select from your hard drive the Raspberry Pi .img from the extracted zip file you wish to write to the SD card.
  • Select the SD card you wish to write your image to.
  • Review your selections and click 'Flash!' to begin writing data to the SD card.

You can find a more in-depth instruction guide to flashing to your SD card at the official Raspberry Pi website (opens new window).

If you used balenaEtcher to flash, the SD card will already have been ejected. Simply take the SD card out and put it back in. The SD card should now be labelled as boot. Next, enable SSH at bootup so you can remotely login by creating an empty file in the SD card root folder called ssh. Eject the SD card through your OS before taking it out of the SD card reader.

RPI4 Console

# Booting up the Raspberry Pi

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 so I SSH’d to that:

ssh -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. Press Ctrl-c to stop monitoring:

sudo watch -n1 vcgencmd measure_temp

Next, let’s change the password for the “pi” user:

passwd pi
RPI4 Console

After that, switch to the root user, which we will use for the remaining part of the tutorial:

sudo su -

# Configuring the storage

We 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
RPI4 Console

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 fdisk

Format the new partition on your SSD:

mkfs.ext4 /dev/sda1

Configure 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 0" | sudo tee -a /etc/fstab
mount -a

While you’re editing /etc/fstab add a RAM filesystem for logs (optional). This is also to prevent burning out your SD card too quickly:

echo 'none /var/log tmpfs size=10M,noatime 0 0' >> /etc/fstab

# Install Docker

apt install apt-transport-https ca-certificates curl gnupg lsb-release -y
curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update
apt -y install docker-ce docker-ce-cli containerd.io

# Create mount for Docker volumes

rm -rf /var/lib/docker
mkdir -p /var/lib/docker
mount --bind /mnt/usb /var/lib/docker
echo "/mnt/usb /var/lib/docker none bind,nobootwait 0 2" >> /etc/fstab
systemctl restart docker

# Configuring the firewall

Upgrade your OS packages to latest:

apt update && apt upgrade -y && apt autoremove

Install a firewall and allow SSH, HTTP, HTTPS, Bitcoin, and Lightning:

apt install -y ufw
ufw default deny incoming
ufw default allow outgoing

UFW needs default iptables changes and a reboot for the firewall to work:

update-alternatives --set iptables /usr/sbin/iptables-legacy

Switch back to root after rebooting:

sudo su -

This command allows SSH connections from internal networks only:

ufw allow from to any port 22 proto tcp
ufw allow from to any port 22 proto tcp
ufw allow from to any port 22 proto tcp
ufw allow from 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 tcp

These 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/tcp

Enable your firewall:

ufw enable

Verify your configuration:

ufw status

# Change your Hostname

echo $host_name | sudo tee /etc/hostname
sed -i -E 's/^*/\t'"$host_name"'/' /etc/hosts
hostnamectl set-hostname $host_name
systemctl restart avahi-daemon

# Setup BTCPay Server

Download BTCPay Server from GitHub:

cd # ensure we are in root home
apt install -y fail2ban git
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker

Configure BTCPay by setting some environment variables (opens new window):

export BTCPAY_HOST="btcpay.local"
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_LIGHTNING="clightning"

If you want to use multiple hostnames, add them via the optional BTCPAY_ADDITIONAL_HOSTS variable:

export BTCPAY_ADDITIONAL_HOSTS="btcpay.YourDomain.com"

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 -i

It should be up and running within a few minutes. Try opening http://btcpay.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.