Documentation repository
Latest commit c435ffd Jan 30, 2016 @jesion jesion Merge pull request #1 from gitter-badger/gitter-badge
Add a Gitter chat badge to
Failed to load latest commit information. Add Gitter badge Jan 30, 2016
network-diagram.svg updated diagram Jan 25, 2016

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.