Developer Prerequisites

The following mandatory pre-requisites must be completed to set up a development environment for BAF.The process of setting up developer pre-requisites can be done manually or via an automation script(currently script is for windows OS only)

Script Based Setup

You can use the scripts here to setup developer prerequisites for Windows or Mac systems.


NOTE: You need to run the script with admin rights. This can be done by right clicking the script and selecting ‘Run as admininstrator’.


Manual Setup

The estimated total effort is 55 mins.


NOTE: You will need at least 8GB RAM to run BAF on local machine.


Setting up Git on your machine

Estimated Time: 10 minutes

To use Git, you need to install the software on your local machine.

  1. Download and install git bash from http://git-scm.com/downloads.

  2. Open ‘git bash’ (For Windows, Start > Run, C:\Program Files (x86)\Git\bin\sh.exe --login -i )

  3. After the install has completed you can test whether Git has installed correctly by running the command git --version

  4. If this works successfully you will need to configure your Git instance by specifying your username and email address. This is done with the following two commands (Use your GitHub username and email address, if you already have a Github Account):

    git config --global user.name "<username>"
    git config --global user.email "<useremail>"
    
  5. To verify that the username and password was entered correctly, check by running

    git config user.name
    git config user.email
    
  6. Windows users should additionally execute the following so that the EOLs are not updated to Windows CRLF.

    git config --global core.autocrlf false
    

Setting up Github

Estimated Time: 5 minutes

GitHub is a web-based Git repository hosting service. It offers all of the distributed revision control and source code management (SCM) functionality of Git as well as adding its own features. You can create projects and repositories for you and your teams’ need.

Complete the following steps to download and configure BAF repository on your local machine.

  1. If you already have an account from previously, you can use the same account. If you don’t have an account, create one.

  2. Go to blockchain-automation-framework on GitHub and click Fork button on top right. This will create a copy of the repo to your own GitHub account.

  3. In git bash, write and execute the command:

    ssh-keygen -q -N "" -f ~/.ssh/gitops
    

    This generates an SSH key-pair in your user/.ssh directory: gitops (private key) and gitops.pub (public key).

  4. Add the public key contents from gitops.pub (starts with ssh-rsa) as an Access Key (with read-write permissions) in your Github repository by following this guide.

  5. Execute the following command to add the key to your ssh-agent

    eval "$(ssh-agent)"
    ssh-add ~/.ssh/gitops
    
  6. Create a project directory in your home directory and clone the forked repository to your local machine.

    mkdir ~/project
    cd ~/project
    git clone git@github.com:<githubuser>/blockchain-automation-framework.git
    
  7. Checkout the develop branch.

    cd blockchain-automation-framework
    git checkout develop
    

NOTE: If you have 2-Factor Authentication enabled on your GitHub account, you have to use GitHub token. Otherwise, password is fine.

How To Generate GitHub Token
  1. On GitHub page, click your profile icon and then click Settings.
  2. On the sidebar, click Developer settings.
  3. On the sidebar, click Personal access tokens.
  4. Click Generate new token.
  5. Add a token description, enable suitable access and click Generate token.
  6. Copy the token to a secure location or password management app.

For security reasons, after you leave the page, you can no longer see the token again.


Setting up Docker

Estimated Time: 10 minutes

Install Docker Toolbox to make sure your local environment has the capbility to execute docker commands. You can check the version of Docker you have installed with the following command from a terminal prompt:

docker --version

NOTE: For Windows, you MUST use Docker Toolbox with VirtualBox. Do not use Docker Desktop for Windows. Also HyperV should be DISABLED for Mac and Windows.


Setting up HashiCorp Vault

Estimated Time: 15 minutes

We need Hashicorp Vault for the certificate and key storage.

  1. To install the precompiled binary, download the appropriate package for your system.

  2. Once the zip is downloaded, unzip it into any directory. The vault binary inside is all that is necessary to run Vault (or vault.exe for Windows). Any additional files, if any, aren’t required to run Vault.

  3. Create a directory project/bin and copy the binary there. Add project/bin directory to your PATH. Run following fron git bash.

    mkdir ~/project/bin
    mv vault.exe ~/project/bin
    export PATH=~/project/bin:$PATH
    
  4. Create a config.hcl file in the project directory with the following contents (use a file path in the path attribute which exists on your local machine)

    ui = true
    storage "file" {
       path    = "~/project/data"
    }
    listener "tcp" {
       address     = "0.0.0.0:8200"
       tls_disable = 1
    }
    
  5. Start the Vault server by executing (this will occupy one terminal). Do not close this terminal.

    vault server -config=config.hcl
    
  6. Open browser at http://localhost:8200/. And initialize the Vault by providing your choice of key shares and threshold. (below example uses 1) ../_images/vault-init.png

  7. Click Download Keys or copy the keys, you will need them. Then click Continue to Unseal. Provide the unseal key first and then the root token to login.

  8. In a new terminal, execute the following (assuming vault is in your PATH):

    export VAULT_ADDR='http://<Your Vault local IP address>:8200' #e.g. http://192.168.0.1:8200
    export VAULT_TOKEN="<Your Vault root token>"
    vault secrets enable -version=1 -path=<Your Secret Engine> kv
    

Setting up Minikube

Estimated Time: 15 minutes

For development environment, minikube can be used as the Kubernetes cluster on which the DLT network will be deployed.

  1. Follow platform specific instructions to install minikube on your local machine. Also install Virtualbox as the Hypervisor. (If you already have HyperV it should be removed or disabled.)

  2. minikube is also a binary, so move it into your ~/project/bin directory as it is already added to PATH.

  3. Configure minikube to use 4GB memory and default kubernetes version

    minikube config set memory 4096
    minikube config set kubernetes-version v1.16.13
    
  4. Then start minikube. This will take longer the first time.

    minikube start --vm-driver=virtualbox
    
  5. Check status of minikube by running

    minikube status
    

    The Kubernetes config file is generated at ~/.kube/config

  6. To stop (do not delete) minikube execute the following

    minikube stop
    

    Now your development environment is ready!

NOTE: Minikube uses port in range 30000-32767. If you would like to change it, use the following command:

minikube start --vm-driver=virtualbox --extra-config=apiserver.service-node-port-range=15000-20000

Troubleshooting

At Step 5, if you get the following error:

2020-03-10T17:00:21.664Z [ERROR] core: failed to initialize barrier: error="failed to persist keyring: mkdir /project: permission denied"

Update the path in Vault config.hcl to absolute path:

storage "file" {
   path    = "/full/path/to/project/vault"
}

For example, /home/users/Desktop/project/vault.