Documentation repository
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Setting up Bushido development environment

Join the chat at

You will need the following software to be installed:

You will need to register on the following websites:

  • Sendgrid - Bushido uses this service to deliver emails. (Minimum requirement)
  • Chain - Bushido uses this service to get transaction notifications (Optional requirement - Bushido can also get transaction notifications on its own)
  • Twilio Authy - Bushido uses this service to provide 2 Factor Authentication feature to users. (Optional requirement - Bushido can run without 2FA)


RabbitMQ is a message broker used on Bushido to wire up server, web and mobile components.

Build RabbitMQ image from this repository rabbitmq. Checkout the code, and once in the rabbitmq folder:

docker build -t bushido-rabbitmq .

Run the RabbitMQ container off this image.

docker run -t -i -e RABBITMQ_DEFAULT_USER=bushido -e RABBITMQ_DEFAULT_PASS=bushido -p 15674:15674 -p 5672:5672 bushido-rabbitmq

Note we open up 2 ports: 15674 for rabbitmq_web_stomp plugin and 5672 for AMQP.


MongoDB is a document-oriented, noSQL database used on Bushido as a data and metadata persistance layer.

Run the MongoDB container.

docker run --name bushido-mongo -d mongo

In a separate console window, launch a MongoDB client to test if its working fine and find out the IP address of MongoDB container.

docker run -it --link bushido-mongo:mongo --rm mongo sh -c "exec mongo $MONGO_PORT_27017_TCP_ADDR:$MONGO_PORT_27017_TCP_PORT/test"

Make a note of the IP address assigned, typically its 172.17.0.x

Bushido Java Service

Bushido Java Service provides server components for Bushido.

Clone bushido-java-service. If you are on Windows, clone to a folder in your user's Documents (eg. C:\Users\JohnDoe\Documents\bushido). It is required by Docker on this OS.

git clone

Once you have the code, locate file in /bushido-java-service/bushido-wallet-service/src/main/resources and change/fill the following entries: //your Docker Machine's IP //MongoDB container's IP
app.sendgrid.username=johndoe //your user name on
app.sendgrid.password=somesecurepassword //your password on

Optionally change these settings:

app.authy.enabled=false //change to true if you want to enable 2FA
app.authy.apikey= //API Key on Twilio Authy, provide if app.authy.enabled == true
app.chainuser= //HTTP Basic Auth user for RESTful notifications
app.chainpass= //HTTP Basic Auth password for RESTful notifications
app.onchainuser= //your user Id on (for notifications subscriptions)
app.onchainpass= //your user password on (for notifications subscriptions)

You are ready to build it with Maven.

mvn install

Once its built, run the docker container off the Tomcat 8 - JRE 7 image defined in this repo tomcat

docker run -it --rm -e JAVA_OPTS="" -e CATALINA_OPTS="-Xms512M" -p 8080:8080 -v //c/Users/JohnDoe/Documents/bushido/bushido-java-service/bushido-wallet-service/target/bushido-wallet-service-1.0.3:/usr/local/tomcat/webapps/walletapi -v //c/Users/JohnDoe/Documents/bushido/bushido-java-service/bushido-address-watcher/target/bushido-address-watcher-1.0.3:/usr/local/tomcat/webapps/blockchain tomcat:8.0

Bushido Web Application

Bushido Web Application is a HTML/JS front-end with wallet, registration, widgets and other modules.

Clone bushido-web-app to bushido folder, follow the instructions from the code repo's readme file.


Nginx is a HTTP and Reverse Proxy server used on Bushido to serve Bushido Web Application, and reverse proxy API calls and socket connections upstream to Tomcat and RabbitMQ.

Clone docker-nginx to bushido folder.

git clone

This repo comes with /conf folder, where you can find Nginx configuaration files and some self-signed SSL certificates. Review the bushido.conf file as you will need to change a few IP addresses there. For dev purpose you can use included self-signed SSL certificate, however you can also generate self-signed certificates if you prefer to.

If you are a Linux user, install OpenSSL with apt-get. If you prefer Windows, get Win32 OpenSSL v1.0.2e.

Generate Root CA certificate. Use common name: Bushido SSL

openssl genrsa -out ca.key 4096
req -new -x509 -days 1826 -key ca.key -out ca.crt

Generate Bushido wildcard unsigned certificate. Use common name: *

genrsa -out star_bushidowallet_com.key 4096
req -new -key star_bushidowallet_com.key -out bushido.csr

Sign wildcard certificate with Root CA's key

x509 -req -days 730 -in bushido.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out bushido.crt

Copy bushido.crt content to bundle.crt and save it. This is your self-signed wildcard certificate. File ca.crt is your Root CA (issuer) certificate. Both .crt files need to be installed in Google Chrome (Settings - Advanced - HTTPS/SSL) in order for the application to work correctly.

Build the image and run the container:

docker build -t bushido-nginx .
docker run --name bushido-nginx -v //c/Users/JohnDoe/Documents/bushido/docker-nginx/conf/nginx.conf:/etc/nginx/nginx.conf -v //c/Users/JohnDoe/Documents/bushido/docker-nginx/conf/bushido.conf:/etc/nginx/conf.d/bushido.conf:ro -v //c/Users/JohnDoe/Documents/bushido/bushido-web-app/dist:/usr/share/nginx/html:ro -v //c/Users/JohnDoe/Documents/bushido/docker-nginx/conf/cert/bundle.crt:/etc/nginx/bundle.crt:ro -v //c/Users/JohnDoe/Documents/bushido/docker-nginx/conf/cert/star_bushidowallet_com.key:/etc/nginx/star_bushidowallet_com.key:ro -d -p 80:80 -p 443:443 bushido-nginx

Configure your hosts file to contain the following entries

IP address is your Docker Machine's IP address.

Bushido Android Application

Bushido Android Application is a mobile wallet app. It talks to back-end via RabbitMQ Server and Java RESTful API. It can receive and spend Bitcoin.

Clone bushido-android-app, install Android Studio and launch the application using emulator or physical android device connected via USB cable.

Utimaco CryptoServer Emulator

Utimaco CryptoServer Emulator can emulate a physical Hardware Security Module device Utimaco CryptoServer. Bushido will be configurable to integrate with Utimaco device to store sensitive data - including Bitcoin keys and perform cryptographic operations in a secure way.

Currently can not publicize the emulator software due to licensing terms.