Installing Samourai Dojo on a Raspberry Pi 4

This document covers the steps required before starting to download and configure Dojo as per instructions

1. Format your external disk to "ext4" or "btrfs" and mount it.

Raspberry Pi 4 boots from and works with a microSD card. While card sizes are getting increasingly bigger and you can get big enough SD cards to hold the entire blockchain as of today, SD Cards are not reliable long term storage and they have limited lives. Best to go with an external drive. I'd suggest going with 1 TB of external storage.

Attach your external storage through one of the USB 3.0 ports. This will attach your storage to the default /media/yourusername/yourexternalstorage location. It's better to make a seperate attachment point for it and make sure your Pi 4 attaches the external disk to the same location every time you reboot.

If you have bought a ready external drive, there's a very good chance that it's formatted to NTFS - that will not work for us. Let's check:

$ sudo lsblk -f
NAME        FSTYPE LABEL     UUID                                 FSAVAIL FSUSE% MOUNTPOINT
└─sda1      ntfs   ELEMENTS  B0FECF48FECF0616                                    
├─mmcblk0p1 vfat   boot      F661-303B                               213M    15% /boot
└─mmcblk0p2 ext4   rootfs    8d008fde-f12a-47f7-8519-197ea707d3d4   12.6G     8% /

You will get something like the above. "mmcblk0" is your SD card. "sda" is your disk and "sda1" is your single partition on that disk.

The following will remove your single partition from your external disk (/dev/sda - without the last number at the end), create a single primary partition and write all the changes to disk. If you have more than one partition, consult the fdisk command help to delete all and create a single partition.

$ sudo umount /dev/sda1        #We're unmounting the disk before doing anything to it
$ sudo fdisk /dev/sda          #Firing up fdisk app with /dev/sda as target (no "1" at the end)

Press the following keys at each prompt to wipe the disk clean and create a fresh partition:
d, n, p, 1, Enter, Enter, Y, w  #The Yes/No prompt will be shown if you are working on an NTFS disk

$ sudo mkfs.ext4 /dev/sda1      #This will format your disk to "ext4" filesystem

Now we need to make it so that we tell the system to mount it to the same location at every boot, automatically. We'll do this by editing the /etc/fstab file and remounting everything.

$ sudo blkid

In the device list that appears find your external disk (probably /dev/sda1) and note down or copy the UUID of it (something like "8d008fde-f12a-47f7-8519-197ea707d3d4").

Next, create a directory to mount the disk to and edit /etc/fstab file:

$ sudo mkdir /your_external_disk_mount_point
$ sudo nano /etc/fstab

Add the following line at the end:

UUID=That_UUID_You_Just_Copied  /your_external_disk_mount_point  ext4  defaults   0   0

Save (^O) and Exit (^X). Then mount everything specified in fstab with:

$ sudo mount -a

2. Install Docker

As of this writing (Sept 13, 2019) the docker included in Raspbian DOES NOT WORK. DO NOT INSTALL IT!

Use the convenience script located at

curl -fsSL -o
sudo sh

3. Install docker-compose through the package manager

$ sudo apt-get install docker-compose

4. Configure docker to use the external disk:

Create a new file "/etc/docker/daemon.json". Add the following lines: { "data-root": "/your_external_disk_mount_point" } Save & exit

5. Restart docker to accept changes

sudo systemctl daemon-reload sudo systemctl start docker

6. Check that docker is using the external disk

sudo docker info | grep "Docker Root Dir:"

7. Download and unzip latest Dojo release

8. Edit bitcoin Dockerfile to use the bitcoin ARM source

         Change line #9 from:
            `ENV     BITCOIN_URL`
            `ENV     BITCOIN_URL`

         Change line #10 from:
            `ENV     BITCOIN_SHA256      600d1db5e751fa85903e935a01a74f5cc57e1e7473c15fd3e17ed21e202cfe5a`
            `ENV     BITCOIN_SHA256      cc7d483e4b20c5dabd4dcaf304965214cf4934bcc029ca99cbc9af00d3771a1f`

Note for future bitcoin upgrades: Here we're basically changing the bitcoin Dockerfile to use the bitcoin image compatible with Raspberry Pi 4 instead of the Desktop compatible version in the default Dockerfile. The above is for Bitcoin v0.18.1

For future bitcoin upgrades, here's how you can find which filename & hash to put in there:

For BITCOIN URL go to , right-click on ARM Linux (the header or 32-bit, NOT 64-bit - Raspbian as of this writing is 32-bit only even if the processor is 64-bit), select "Copy link location" and paste it into the BITCOIN_URL line.

For BITCOIN_SHA256 on that same page click the "Verify release signatures" link and open the file with a text editor. This link is the same one as in the Dockerfile we're editing, specified in BITCOIN_ASC_URL. You will see the hashes for the sha256 signatures for various platforms. The one we're looking for is "bitcoin-version-arm-linux-gnueabihf.tar.gz". Copy the long string of letters & numbers across it and paste it into the BITCOIN_SHA256 line.

9. Edit mysql Dockerfile to use a raspberry pi compatible database

Even though Raspberry Pi 4 uses a 64-bit armv8 processor Raspbian reports it as arm64v7. There's no mysql or mariadb docker version for arm64v7. We'll have to use a different compatible database.

         Change line #1 from:
            `FROM    mysql:5.7.25`
            `FROM    hypriot/rpi-mysql:latest`

10. Configure Dojo Installation

Edit the three Dojo configuration files. Refer to Dojo setup instructions

11. Install Dojo

Start Dojo installation script

sudo ./ install

12. Configure your database

At this point your dojo looks like it's running smoothly - but it's NOT!!!!

If you go into your maintenance tool, it should look like everything is OK, you can pair your wallet, etc. However, if you look at the API tab, you'll see an error. We need to fix that:

WARNING: You need to do this every time you restart your dojo

sudo docker exec -it db bash
mysql -h"db" -u"root" -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE" < /docker-entrypoint-initdb.d/1_db.sql

Now if you go into your API tab, you should see some info like uptime, etc.

Congradulations, your dojo node is working!

Optional: Check that everything is running

Bitcoin node sync will take a long time. In order to avoid discovering that your setup was incorrect and dojo doesn't really work after days of downloading the blockchain it's a good idea to check that all docker containers are running properly

sudo docker ps -a

should show 5 containers (nginx, nodejs, bitcoind, db, tor) running


Both compiling the various components and more importantly bitcoin blockchain syncing and verification will significantly tax the CPU. Raspberry Pi 4 runs extremely hot. The CPU and the network chip get very hot. Unless you provide an adequate cooling solution CPU will thermal throttle very quickly, slowing down your Pi 4 significantly. Do NOT use the official Raspberry Pi 4 case, it is horrible. Opt for a case with active cooling or a passive heatsink-case like the FLIRC.

If you are running with the 013701 firmware that is in the original shipping Pi 4s, you might want to upgrade your firmware. There's a patch that affects the USB controller and lowers the temperature by about 3-5 C.


Bitcoin blockchain sync will take around two weeks. Much longer if you do not provide adequate cooling. If you wish to avoid waiting for a sync and want to copy over blockchain data from another node, here are two different methods. First one is easier but you might run into problems.

Method 1:

Copy over the data from your fully synced node to <your_docker_root_dir>/volumes/my-dojo_data-bitcoind/_data/

Set ownership of <your_docker_root_dir>/volumes/my-dojo_data-bitcoind/_data/ and everything under it to user 1105 group 1108:

sudo chown -R 1105:1108 <your_docker_root_dir>/volumes/my-dojo_data-bitcoind/_data/* 

Method 2:

Follow the instructions here:

If you follow the instructions above and still get errors, look at the bitcoin error logs. Very often it'll be a case of wrong permissions or some lockfile which you should delete.


Huge thanks to Nicholas, Laurent MT, Mr Hash and BTCxZelko on Dojo Telegram group - this wouldn't have been possible without you.

Last updated