How to Setup A Bitcoin Full Node with Dojo in Linux

Bitcoin is an innovative and liberating tool. It allowed an individual to obtain an independent resource that he/she can use to easily exchange with other people online. This is because, unlike electronic cash, Bitcoin generates scarcity by limiting the total amount of coins that can circulate in its network.

Knowing that, one way to start using Bitcoin for transactions is by using a full node with a mobile wallet. In that regard, one of the best tools that you can use today is Dojo with Samourai Wallet.

How Does Bitcoin Work?

At its core, Bitcoin is a distributed database that keeps track of records in an immutable way. It creates a system that does three things:

  • Every new entry in the database depends on the previous one. This creates a historical chain of events that links all of the entries to each other.
  • Adding a new entry requires you to do a certain amount of work. This ensures that anyone who attempts to forge an entry needs to redo that work as well any work done after it.
  • Every full node in the network gets a copy of the database and follows a simple set of rules. This, in turn, allows every participant to agree on what is the correct version of history.

Knowing that, these characteristics of Bitcoin ensure that every new entry in the system is just as secure as the previous one. Not only that, its decentralized nature also allows it to run without any central authority.

This makes Bitcoin incredibly useful for individuals that want to transact privately without any third parties.

Why Use a Bitcoin Full Node?

A Bitcoin full node is a software that allows you to become an independent participant in the Bitcoin network. It provides you with an exact copy of the network’s transaction history and allows you to do a number of things that is not possible from a normal Bitcoin wallet.

For example, having the entire transaction history allows a full node to verify any incoming transaction by itself. This can be especially helpful for users who accept Bitcoin for their business.

Running a full node also allows you to become an archive for the Bitcoin network. Other users that want to have their own full node will be able to use yours as a starting point.

Lastly, using a full node also removes the need for external servers whenever you check and broadcast new transactions. This can also be useful for users that want to have security and privacy while using Bitcoin.

One of the easiest ways that you can do to use a full node is by installing Dojo.

What is Dojo?

Dojo is a powerful software suite that allows you to easily create and deploy a secure Bitcoin node. Dojo also aims to maintain a high degree of security through the use of several privacy-enhancing addons as well as Tor.

Bitcoin Dojo Install 05 Dojo Server Website

One important thing to note is the actual installation of Dojo can be both a resource intensive and time consuming process, even though the installation steps are easy.

This is mainly because getting the history of Bitcoin transactions requires your computer to verify every entry that it receives. For example, my Core 2 Duo machine from 2011 took 5 days to fully synchronize with the network.

Bitcoin Dojo Install 06 Bitcoin Long Sync Times

Further, it is also a good practice to make sure that your computer can store all of these data. For the most part, a 1TB drive should be enough to store the entire history as well as leave space for new ones.

This article will focus on installing Dojo on an Ubuntu 22.04 machine. While most of the commands should work for any Linux distribution, the names of the packages as well as programs may vary.

Preparation for Dojo Installation in Ubuntu Linux

To get started, you need to first create a new user account in the system:

sudo useradd -s /bin/bash -d /home/dojo -m -G sudo dojo
sudo passwd dojo
Bitcoin Dojo Install 07 Create New User

The reason for this is to separate any configuration and program that Dojo will run from your user account. A separate account will also reduce the chance for any user error to affect Dojo.

Once done, you can switch to the Dojo user by running: su dojo. From here, you can then start installing some distribution-specific dependencies:

sudo apt update
sudo apt install gnupg-agent ca-certificates curl software-properties-common unzip tor torbrowser-launcher
Bitcoin Dojo Install 26 Install Dependencies Ubuntu 1

The next thing that you need to do is to include the repository for Docker and Docker Compose.

Download and import the primary signing key for Docker releases:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

Next, add the Docker repository:

sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt update
Bitcoin Dojo Install 08 Add Docker Keys

Lastly, install Docker:

sudo apt install docker-ce docker-ce-cli
sudo usermod -aG docker dojo

Also install docker-compose:

sudo curl -L "https://github.com/docker/compose/releases/download/1.25.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
Bitcoin Dojo Install 09 Docker Compose Version

With Docker installed, you can now start downloading Dojo to your machine:

wget https://code.samourai.io/dojo/samourai-dojo/-/archive/master/samourai-dojo-master.zip
Bitcoin Dojo Install 10 Dojo Zip Download

Extract all the Dojo files to your machine:

mkdir /home/$USER/dojo
unzip /home/$USER/samourai-dojo-master.zip -d /home/$USER/dojo
Bitcoin Dojo Install 11 Dojo Unzip Directory

Configuring Dojo’s Secret Keys

Open the file “docker-bitcoind.conf.tpl” in the dojo folder:

nano /home/$USER/dojo/docker/my-dojo/conf/docker-bitcoind.conf.tpl

The variables that you need to edit here are the BITCOIN_RPC_USER= and BITCOIN_RPC_PASSWORD=. These are the values that Dojo uses to connect to other remote wallets:

BITCOIN_RPC_USER=dojo
BITCOIN_RPC_PASSWORD=random_password
Bitcoin Dojo Install 13 Bitcoind Conf Sample

Modifying the Dojo Database

The next file that you need to edit is the “docker-mysql.conf.tpl” file. This is the file that holds all the information that is not directly related to your full node:

nano /home/$USER/dojo/docker/my-dojo/conf/docker-mysql.conf.tpl

You need to edit three variable in this configuration file. These are: MYSQL_ROOT_PASSWORD=, MYSQL_USER= and MYSQL_PASSWORD=:

MYSQL_ROOT_PASSWORD=your_mysql_root_password
MYSQL_USER=dojo
MYSQL_PASSWORD=mysql_user_password
Bitcoin Dojo Install 14 Mysql Config Sample

Modifying the NodeJS Configuration

The next file to edit is the “docker-node.conf.tpl.” This is the file that controls the Dojo frontend instance. It also serves as the glue that combines the full node, MySQL and all the extra features that Dojo uses:

nano /home/$USER/dojo/docker/my-dojo/conf/docker-node.conf.tpl

Inside this file, you need to edit the following variables: NODE_API_KEY=, NODE_ADMIN_KEY= and NODE_JWT_SECRET=.

  • The NODE_API_KEY serves as the primary secret key for your Dojo’s REST API. This value is what will allow other services to easily communicate with Dojo when necessary.
  • The NODE_ADMIN_KEY is the primary password for your Dojo instance. This is what you will type whenever you want to access your Dojo’s configuration panel.
  • The NODE_JWT_SECRET serves as the primary salt for your Dojo’s Web Token system. In that, it is the value that makes sure that there is a strong encryption for every Dojo session.
NODE_API_KEY=random_node_api_key
NODE_ADMIN_KEY=random_node_admin_key
NODE_JWT_SECRET=random_node_jwt_secret
Bitcoin Dojo Install 15 Nodejs Config Sample

Configuring the Bitcoin Block Explorer

Lastly, you need to edit the “docker-explorer.conf.tpl” file. This is what controls the internal block explorer for Dojo:

nano /home/$USER/dojo/docker/my-dojo/conf/docker-explorer.conf.tpl

You need to edit two variables in this configuration file. These are: EXPLORER_INSTALL= and EXPLORER_KEY=. The first variable tells Dojo that you want to install the block explorer. The second variable serves as the password for the application.

EXPLORER_INSTALL=on
EXPLORER_KEY=random_key
Bitcoin Dojo Install 16 Block Explorer Config Sample

Installing the Dojo Bitcoin Node in Ubuntu

With that done, the next thing that you need to do is to start the Dojo installation script. All you need to do is to run the following command:

/home/$USER/dojo/docker/my-dojo/dojo.sh install

The installation script will now download all the necessary tools that it needs to build Dojo’s docker container. Once it is done, it will then start a compilation process where it will build both the tools and programs that it needs.

Bitcoin Dojo Install 17 Docker Compile Tools

From there, the script will start the Dojo executable and immediately synchronize with the Bitcoin network. The script will indicate this with a difference in layout and color of the terminal. At this point, you can now press Ctrl + C to fork the process to the background.

Bitcoin Dojo Install 18 Dojo Sync Progress

Checking on Dojo’s Sync Progress

As discussed above, synchronizing with the Bitcoin network can take from a few hours to a few days. As such, it is important to keep track of the node’s progress and look for any potential issues during the sync.

There are two ways that you can do to check Dojo’s progress. First, you can use the “dojo.sh” file to generate a running log of the server. This is especially useful if you want a quick way of looking at the server’s progress. For example, running this command will display all the logs related to the Bitcoin full node:

/home/$USER/dojo/docker/my-dojo/dojo.sh logs bitcoind
Bitcoin Dojo Install 19 Dojo Logs Command

It is also possible to check Dojo progress through its dedicated web portal. However, you need to make sure that your computer has a copy of the Tor browser. With that, you can run the following command to print all the onion addresses that Dojo uses:

/home/$USER/dojo/docker/my-dojo/dojo.sh onion

From there, you need to copy and load the address for the “Dojo API and Maintenance Tool” through the Tor browser. Doing this will load a small prompt where you can type the admin key that you added earlier.

Bitcoin Dojo Install 20 Maintenance Tool Login

Dojo will then display a brief summary of your node as well as the various states of its services. This is helpful if you want to have a more comprehensive look at your Dojo instance.

Bitcoin Dojo Install 21 Summary Screen

Pairing Samourai Wallet with Dojo

Once your Dojo node is properly synchronized with the Bitcoin network, you can now pair your mobile wallet to it. By default, the Dojo full node works well with Samourai Wallet for Android. As such, this article will focus on pairing your Dojo with Samourai.

Bitcoin Dojo Install 22 Samourai Wallet Website
  1. Download Samourai wallet from the Play Store.
  2. Run Samourai Wallet and enable “Connect to your own Dojo server.” From there, click “Scan QR.”
Bitcoin Dojo Install 24 Samourai Wallet Dojo Pair
  1. On your Dojo’s Maintenance Tool, click the “Pairing” option on the website’s left hand menu. This will generate a QR code for you to scan.
Bitcoin Dojo Install 25 Dojo Pair Qr Code
  1. Go back to your Samourai Wallet and scan the QR code in the website.

Congratulations! You have setup your own Bitcoin full node through Dojo.

Frequently Asked Questions

Can I use the same password for the Dojo secret keys?

Yes, but we do not encourage that. The Dojo full node relies on the keys that you provide for some of its sensitive functions. Should an attacker manage to take control of your single key, it is possible for him to snoop and modify your transactions.

Dojo is stuck at 5% while connecting to Tor. Is my Bitcoin node broken?

This is most likely happening because Docker cannot establish a proper external connection. One of the reasons why this might happen is that your machine has both the apt and snap versions of Docker.

The step to fix this is to remove every instance of Docker, and reinstall Docker with only one version.

I am having a “task: bitcoind blocked for more than 120 seconds” error. What is wrong with my Dojo?

This is most likely happening because your machine is running out of resources during synchronization. Because of that, the program trips a “self-hang” state where it waits until there’s sufficient resources available. There are instances where this leads to a complete system lock.

It is important to make sure your computer has the sufficient resources to synchronize and manage a Bitcoin node. Your machine should have at least 1TB of space and 8GB of RAM to comfortably synchronize with the Bitcoin network.

Image credit: Fernando Hernandez via Unsplash

Is this article useful?

Subscribe to our newsletter!

Our latest tutorials delivered straight to your inbox

How to Set Up a Bitcoin Full Node With Dojo in Linux