Dojo Vanilla on Linux x86

Info

In this howto I go through all the steps for installing Dojo Vanilla on your Linux X86. The installations needs an already installed Bitcoin Core and an indexer like Fulcrum. However, I also go into the points where you can install these two components via Dojo Vanilla.

Preparation

Before we start with the installation we have to install docker and docker-compose on our system.

sudo apt-get update 

sudo apt-get install ca-certificates unzip curl gnupg lsb-release

Adding GPG-keys

sudo mkdir -p /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Adding repo for docker

sudo echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Check if docker is installed correctly

docker --version

The output must look like this

Docker version 20.10.21, build baeda1f

Adding your system user to the docker group

sudo usermod -aG docker $USER

Now you have to logout and login again

Download Dojo Vanilla

cd ~/Downloads

In the next step we visit the repo from Samourai and download the latest version of Dojo Vanilla.

wget https://code.samourai.io/dojo/samourai-dojo/-/archive/v1.18.1/samourai-dojo-v1.18.1.zip

Unzip the file

unzip samourai-dojo-v1.18.1.zip -d .

Now we want to rename the unzipped folder and move it in our user home directory

mv samourai-dojo-v1.18.1 ~/Dojo

Configuration

In this step we must edit some configuration files. To do so we have to change to our Dojo directory.

cd ~/Dojo/docker/my-dojo

Here we can find a directory called conf

cd conf

In this directory we can find every configuration file for Dojo Vanilla. Be careful we only want to edit the .tpl files!

docker-bitcoind.conf.tpl

nano docker-bitcoind.conf.tpl

change the RPC_USER and RPC_PASSWORD

BITCOIND_RPC_USER=dojorpc

change to

BITCOIND_RPC_USER=nakamoto

BITCOIND_RPC_PASSWORD=dojorpcpassword

change to

BITCOIND_RPC_PASSWORD=satoshi

We scroll a little bit further to the setting for BITCOIND. If we don't have a running Bitcoin Core installation we have to set the parameter to on, if we don't have a Bitcoin Core installation we set it to off. In this howto we don't want to use the Bitcoin Core installation from Dojo Vanilla.

BITCOIND_INSTALL=on

change to

BITCOIND_INSTALL=off

change the ip-address for BITCOIND

BITCOIND_IP=172.28.1.5

to

BITCOIND_IP=192.168.100.242

(change the 192.x.x.x to you ip-address)

Change the port

BITCOIND_PORT=28256

to

BITCOIND_PORT=8332

Change the parameter for ZMQ, we can find the settings in our bitcoin.conf

BITCOIND_ZMQ_RAWTXS

BITCOIND_ZMQ_RAWTXS=9501

change to

BITCOIND_ZMQ_RAWTXS=28333

BITCOIND_ZMQ_BLK_HASH

BITCOIND_ZMQ_BLK_HASH=9502

change to

BITCOIND_ZMQ_BLK_HASH=28334

Now we save the config file with STRG + x and enter.

docker-common.conf.tpl

We can leave everyting as it is.

docker-explorer.conf.tpl

If we want to install the bitcoin explorer with Dojo Vanilla we set the parameter to on, otherwise to off.

docker-indexer.conf.tpl

In this configuration file we can configure our indexer. If you have already installed an indexer like Fulcrum or Electrum set the setting "INDEXER_INSTALL" to off. For an external Fulcrum indexer:

INDEXER_TYPE=addrindexrs

change to

INDEXER_TYPE=fulcrum

change the ip-address

INDEXER_IP=172.28.1.6

to

INDEXER_IP=192.168.100.242

Change the port for the indexer

INDEXER_PORT=50001

to

INDEXER_PORT=50002

For a Fulcrum server we have to set the parameter for the indexer batch support to active.

INDEXER_BATCH_SUPPORT=inactive

Set to active

INDEXER_BATCH_SUPPORT=active

For tls

INDEXER_PROTOCOL=tcp

Change to tls

INDEXER_PROTOCOL=tls

Now we save the config file with STRG + x and enter.

docker-mysql.conf.tpl

In this config file we have to change all the passwords for security reasons. You should use a password manager like KeePass or Bitwarden to generate randomized passwords.

MYSQL_ROOT_PASSWORD=rootpassword

Change to

MYSQL_ROOT_PASSWORD=asdfjlkafgbuiower

MYSQL_PASSWORD=rootpassword

change to

MYSQL_PASSWORD=8986798hjdfserterst

Now we save the config file with STRG + x and enter.

docker-node.conf.tpl

In this config file we set the password for our Dojo Maintenance Tool (DMT). I also recommend to use KeePass or Bitwarden for randomized passwords.

NODE_API_KEY=myApiKey

change to

NODE_API_KEY=8986798hjdfserterst

Now we set the password for the login.

NODE_ADMIN_KEY=myAdminKey

change to

NODE_ADMIN_KEY=8986798hjdfserterst

In the last step we have to change the indexer.

NODE_ACTIVE_INDEXER=local_bitcoind

change to

NODE_ACTIVE_INDEXER=local_indexer

Save the config file with STRG + x and enter.

docker-whirlpool.conf.tpl

If we want to run whirlpool with our Dojo Vanilla installation, we have to set the following parameter to on.

WHIRLPOOL_INSTALL=off

change to

WHIRLPOOL_INSTALL=on

Save the config file with STRG + x and enter.

Info: Alternatively, we can install Whirlpool manually. This gives us the option to mix directly to an external XPUB after X rounds. You can find the steps below.

Dojo Vanilla installation

Now we install Dojo Vanilla with our new configuration.

./dojo.sh install

We confirm with "y"

Our Dojo is ready as soon as we see "INFO Tracker: Processing active Mempool". It can take a little wile.

Alternative Whirlpool installation

If we want to install Whirlpool manually, we go to https://code.samourai.io/whirlpool/whirlpool-client-cli/-/releases where we can find the latest Whirlpool CLI version.

The advantage of a separate installation would be the easy setup for the Mix-to-XPUB feature.

Before we can start, we need to install Java. On Ubuntu we just type java in the terminal to see the possible options.

java

sudo apt install openjdk-18-jre-headless

Now we create a directory for Whirlpool

mkdir ~/Whirlpool

We change into the directory

cd ~/Whirlpool

In the next step we download the latest version from the Samourai Whirlpool CLI repo.

wget https://code.samourai.io/whirlpool/whirlpool-client-cli/uploads/63621e145967f536a562851853bd0990/whirlpool-client-cli-0.10.16-run.jar

Create a service file for our Whirlpool

sudo nano /etc/systemd/system/whirlpool.service

Insert

[Unit]
Description=Whirlpool
After=tor.service

[Service]
WorkingDirectory=/home/nakamoto/Whirlpool
ExecStart=/usr/bin/java -jar whirlpool-client-cli-0.10.16-run.jar --server=mainnet --tor --auto-mix --mixs-target=0 --listen
User=nakamoto
Group=nakamoto
Type=simple
KillMode=process
TimeoutSec=60
Restart=always
RestartSec=60

[Install]
WantedBy=multi-user.target

Save the file with STRG + x and enter.

Enable the service

sudo systemctl enable whirlpool

We don't want to start the service now!

Info: If there are any Whirlpool CLI updates, we have to adjust the line with ExecStart in the service file!

Installation Whirlpool GUI

From the Samourai website we want to download the current version of Whirlpool GUI and install it.

Done

All installation steps are now complete. If you want to know all the commands of dojo.sh, you can find them on the Samourai repo.

Upgrade

cd ~/Dojo/docker/my-dojo

Stop Dojo

./dojo.sh stop

Start the upgrade

./dojo.sh upgrade

Connect our Samourai Wallet with Dojo and Whirlpool

Visit Dojo Maintenance Tool

With the following command we get the onion-address for our DMT

./dojo.sh onion

Now we start the Tor browser and visit the onion-address. The password is the one from our docker-node-tpl.conf (NODE_ADMIN_KEY).

Installation Samourai Wallet

We download the Samourai Wallet from the website https://samouraiwallet.com. It can be found under "Download". There are several options. Either a direct download of the APK file, via F-Droid or Google Play.

We start the wallet and select MAINNET or TESTNET depending on our Dojo installation. Then we click on "Get Started". Now we select the directory where the wallet backups should be stored. After that we choose if we want to enable Tor. We need Tor for the connection for Dojo. Then we click on Dojo and scan the QR code that we find in the Dojo Maintenance Tool under Tools - Pairing. If everything is okay, the Dojo status should say "Connected".

Now we need to set a passphrase, it has to be SECURE! We write down the 12 words we need in a recovery along with the passphrase. If you want a recovery sheet, you can find it here.

The wallet is now fully installed and set up.

Connect our wallet with our Whirlpool CLI

java -jar whirlpool-client-cli-0.10.16-run.jar --init

INPUT REQUIRED for Pairing Payload - here we need to enter our Pairing Payload, which we can find in our Samourai Wallet under Settings -> Transactions -> Experimental. We copy and paste it into the query.

INPUT REQUIRED for passphrase - here we enter our passphrase of the wallet.

Now we start Whirlpool

sudo systemctl start whirlpool

Check if everything is okay

sudo systemctl status whirlpool

Mix-to-XPUB

If we want to mix to an external XPUB, we have to configure it. We do this with the --set-external-xpub parameter.

We run the command

java -jar whirlpool-client-cli-0.10.16-run.jar --set-external-xpub

In the query "External BIP84 XPub/ZPub" we enter the XPUB.

In the next query "Chain?(0)" (default for m/84'/0') we enter 0.

In the next query "Mixs?(>0)>" we enter the number of mix rounds before the mixed UTXOs are sent to cold storage.

INPUT REQUIRED Continue y/n - here we check 3 addresses that were calculated from our ZPUB. We should check them with the wallet from our cold storage. If they match, we confirm with y.

With these steps everything is now set up in the whirlpool.cli.properties file. We can start and stop Whirlpool normally via our Whirlpool Service.

Connect Whirlpool GUI - Whirlpool CLI

To hook up Whirlpool GUI with Whirlpool CLI we need the ip-address of Whirlpool CLI and an apiKey.

We start Whirlpool GUI and click on Advanced: remote CLI. In the field we set the ip-address of your Dojo server. We leave the port 8899 as it is.

Example:

https://192.168.100.242:8899

In the Whirlpool directory we find a file called "whirlpool-cli-config.properties". In this file we will find a setting called "cli-apiKey". This is the api key we need for the connection.

cat ~/Whirlpool/whirlpool-cli-config.properties

No we click on "Connect"

Finally we will be asked for the passphrase, after entering it everything is connected.

You can generate receiving addresses with Whirlpool GUI under Deposit, which means that you do not have to open the Samourai wallet. Whirlpool GUI does not have to be running during the mix.

SCODE: If Samourai offers a discount on the fees for mixes, we can enter it under "Configuration".

Under System - Reset you can reset everything.

All information can be found on the Samourai website.