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:
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.
1
$ sudo umount /dev/sda1 #We're unmounting the disk before doing anything to it
2
$ sudo fdisk /dev/sda #Firing up fdisk app with /dev/sda as target (no "1" at the end)
3
4
Press the following keys at each prompt to wipe the disk clean and create a fresh partition:
5
d, n, p, 1, Enter, Enter, Y, w #The Yes/No prompt will be shown if you are working on an NTFS disk
6
7
$ sudo mkfs.ext4 /dev/sda1 #This will format your disk to "ext4" filesystem
Copied!
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.
1
$ sudo blkid
Copied!
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:
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 https://bitcoincore.org/en/download/ , 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.
Edit the three Dojo configuration files. Refer to Dojo setup instructions
11. Install Dojo
Start Dojo installation script
sudo ./dojo.sh 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
1
sudo docker exec -it db bash
2
mysql -h"db" -u"root" -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE" < /docker-entrypoint-initdb.d/1_db.sql
Copied!
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
Warning:
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.
Optional:
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:
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.
Credits
Huge thanks to Nicholas, Laurent MT, Mr Hash and BTCxZelko on Dojo Telegram group - this wouldn't have been possible without you.