Run your own Samourai Dojo and Whirlpool client on Ubuntu Server – Upgrade your Bitcoin Node

If you prefer video and don’t need a text based guide to install your own Samourai Dojo and Whirlpool client on Ubuntu server, see this video for instructions. Use the below text as a way to help when you run in to something you don’t understand.

Install Samourai Dojo

This guide is intended to be used by users who intend to spend sats. Spending bitcoin leaves a permanent mark on the timechain, and if you want to spend privately it’s best to use Samourai’s post-mix spending tools to do so. Installing your own Dojo and pairing that with a Samourai mobile wallet on android is a great way to mix coins and then spend them in a way that preserves your privacy in a self-sovereign manner.

It is important to note that Samourai Wallet is only available on android devices.

  • Login to your node and go to your downloads directory with [cd downloads]
  • We will need to unzip a file so we need software to do that. Install that with [sudo apt install unzip]
  • Go to Samourai’s dojo downloads page and copy the path to their latest release
  • Download with command [wget <filepath>]
  • Unzip with [unzip samourai-dojo-v1.15.0] (keep an eye on version number)
  • You should already have docker setup on your Ubuntu server from the mempool guide we did previously
  • cd into your home directory with [cd ~]
  • Make a new directory with [mkdir dojo-app]
  • You should see that directory now with [ls]
  • Now let’s move the samourai download to that new directory with [mv ~/downloads/samourai-dojo-v1.15.0/* ~/dojo-app/] (be aware of version number and change to yours)
  • You should see a new directory in the dojo-app directory [cd dojo-app] then [ls]
  • cd into the conf folder with [cd docker/my-dojo/conf/
  • Type [ls] to see the different conf files that all need editing
  • First file we will edit is the bitcoind conf [nano docker-bitcoind.conf.tpl]
  • It’s a long file. Find the lines below and edit them for your setup. We need to update the bitcoind username and password. We need to tell dojo not to install bitcoind since you already have it installed. We need to update the IP address to match your node’s IP address. And we need to update some port settings to match your bitcoind installation. In a second terminal you can login to your node to see your bitcoind settings and verify that they match the lines below [nano .bitcoin/bitcoin.conf]

BITCOIND_RPC_USER=<bitcoind user name>

BITCOIND_RPC_PASSWORD=<Bitcoind user password>

  • Control x, y, enter to save and exit that
  • Next edit [nano docker-explorer.conf.tpl] and edit one line:
  • Next edit [nano docker-indexer.conf.tpl] and edit these lines:
  • Control x, y, enter to save and exit
  • Next edit [nano docker-mysql.conf.tpl] you will be entering some passwords here that are sensitive. You may want to use a password manager to generate these and save them securely.
  • Control x, y, to save and exit
  • Next edit [nano docker-node.conf.tpl] and edit the lines with more strong passwords:
  • cd back one directory with [cd ..]
  • Use [./ install] to install. It will ask you to confirm
  • This is going to take some time to finish. Leave running in the background and use a different terminal for now
  • In the new terminal cd into your my-dojo directory with [cd dojo-app/docker/my-dojo/]
  • Get your onion address with [./ onion]
  • Copy your onion address and paste it into a tor browser. Add [/admin] at the end of it.
  • This password is the NODE_ADMIN_KEY password you set earlier
  • Underneath “tools” click “Pair”
  • In the Samourai wallet android app, setup your wallet. It is recommended that you use a fresh wallet for this. Go through the wallet setup instructions and be sure to use a strong passphrase. Be sure to backup your wallet in a way that cannot be corrupted.

Install Whirlpool CLI

  • In a terminal, make a whirlpool directory with [mkdir whirlpool]
  • cd into that with [cd whirlpool]
  • Find the whirlpool client here:
  • In the terminal type [wget] keep an eye on the version number
  • We need java installed on our node for whirlpool cli to work. The command [java] to see a list of available java installs. Use the most recent version. The command will look something like this depending on the latest version number available [sudo apt install openjdk-17-jre-headless]
  • Then run [java -jar whirlpool-client-cli-0.10.15-run.jar –init] keep an eye on version number and make sure it matches what you downloaded.
  • It will ask you for your pairing payload from your Samourai wallet. You can find that under settings à transactions à experimental à pair to whirlpool GUI. It is a long string of characters that you can copy. That should be pasted into the terminal request and hit enter
  • It might ask you to OK using over tor. Say yes. It will ask you for your wallet’s passphrase. Enter that. CLI will be running in that window.
  • Control C to stop the service so that we can setup a service file to ensure whirlpool fires up everytime your nodes powers on.
  • Use the command [sudo nano /etc/systemd/system/whirlpool.service] to add that file and copy and paste this in (keep an eye on version number, change the NODEUSERNAME places to yours)

ExecStart=/usr/bin/java -jar whirlpool-client-cli-0.10.15-run.jar --server=mainnet --tor --auto-mix --mixs-target=0 --listen

  • Let’s start that with [sudo systemctl daemon-reload]
  • Enable with [sudo systemctl enable whirlpool]
  • Start with [sudo systemctl start whirlpool]
  • Check status with [sudo systemctl status whirlpool]
  • If status looks good you can now download the Whirlpool GUI to your computer (not your Bitcoin node, the computer you will interface with your node) here
  • Open up the GUI and select advanced option
  • In the URL type <your node’s IP address>:8899
  • In the API key you can find that in a file in your whirlpool directory called Nano into that with [nano] and you should see that key that you need to copy and paste into the whirlpool GUI.
  • The GUI will ask you for your wallet’s passphrase

At this point you can navigate around the GUI and learn the different mixing pools available, configurations, etc.