Project: BigchainDB (App Definition and Development / Database)
File: run-dev-network-stack.md

<! Copyright 2020 Interplanetary Database Association e.V., BigchainDB and IPDB software contributors. SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0) Code is Apache-2.0 and docs are CC-BY-4.0 > NOT for Production Use You can use the following instructions to deploy a single or multi node BigchainDB network for dev/test using the extensible `stack` script(s). Currently, this workflow is only supported for the following Operating systems: Ubuntu >= 16.04 CentOS >= 7 Fedora >= 24 MacOSX Minimum resource requirements for a single node BigchainDB dev setup. The more the better: Memory >= 512MB VCPUs >= 1 Note: If you're working on BigchainDB Server code, on a branch based on recent code, then you already have local recent versions of stack.sh and unstack.sh in your bigchaindb/pkg/scripts/ directory. Otherwise you can get them using: ```text $ export GIT_BRANCH=master $ curl -fOL https://raw.githubusercontent.com/bigchaindb/bigchaindb/${GIT_BRANCH}/pkg/scripts/stack.sh $ curl -fOL https://raw.githubusercontent.com/bigchaindb/bigchaindb/${GIT_BRANCH}/pkg/scripts/unstack.sh ``` If you run `stack.sh` out of the box i.e. without any configuration changes, you will be able to deploy a 4 node BigchainDB network with Docker containers, created from `master` branch of `bigchaindb/bigchaindb` repo and Tendermint version `0.22.8`. Note: Run `stack.sh` with either root or non-root user with sudo enabled. ```text $ bash stack.sh ...Logs.. ......... ......... Finished stacking! ``` The `stack.sh` script has multiple deployment methods and parameters and they can be explored using: `bash stack.sh -h` ```text $ bash stack.sh -h Usage: $ bash stack.sh [-h] Deploys the BigchainDB network. ENV[STACK_SIZE] Set STACK_SIZE environment variable to the size of the network you desire. Network mimics a production network environment with single or multiple BDB nodes. (default: 4). ENV[STACK_TYPE] Set STACK_TYPE environment variable to the type of deployment you desire. You can set it one of the following: ["docker", "local", "cloud"]. (default: docker) ENV[STACKTYPEPROVIDER] Set only when STACK_TYPE="cloud". Only "azure" is supported. (default: ) ENV[STACKVMMEMORY] (Optional) Set only when STACK_TYPE="local". This sets the memory of the instance(s) spawned. (default: 2048) ENV[STACKVMCPUS] (Optional) Set only when STACK_TYPE="local". This sets the number of VCPUs of the instance(s) spawned. (default: 2) ENV[STACKBOXNAME] (Optional) Set only when STACK_TYPE="local". This sets the box Vagrant box name of the instance(s) spawned. (default: ubuntu/xenial64) ENV[STACK_REPO] (Optional) To configure bigchaindb repo to use, set STACK_REPO environment variable. (default: bigchaindb/bigchaindb) ENV[STACK_BRANCH] (Optional) To configure bigchaindb repo branch to use set STACK_BRANCH environment variable. (default: master) ENV[TM_VERSION] (Optional) Tendermint version to use for the setup. (default: 0.22.8) ENV[MONGO_VERSION] (Optional) MongoDB version to use with the setup. (default: 3.6) ENV[AZURECLIENTID] Only required when STACKTYPE="cloud" and STACKTYPE_PROVIDER="azure". Steps to generate: https://github.com/Azure/vagrant-azure#create-an-azure-active-directory-aad-application ENV[AZURETENANTID] Only required when STACKTYPE="cloud" and STACKTYPE_PROVIDER="azure". Steps to generate: https://github.com/Azure/vagrant-azure#create-an-azure-active-directory-aad-application ENV[AZURESUBSCRIPTIONID] Only required when STACKTYPE="cloud" and STACKTYPE_PROVIDER="azure". Steps to generate: https://github.com/Azure/vagrant-azure#create-an-azure-active-directory-aad-application ENV[AZURECLIENTSECRET] Only required when STACKTYPE="cloud" and STACKTYPE_PROVIDER="azure". Steps to generate: https://github.com/Azure/vagrant-azure#create-an-azure-active-directory-aad-application ENV[AZURE_REGION] (Optional) Only applicable, when STACKTYPE="cloud" and STACKTYPE_PROVIDER="azure". Azure region for the BigchainDB instance. Get list of regions using Azure CLI. e.g. az account list-locations. (default: westeurope) ENV[AZUREIMAGEURN] (Optional) Only applicable, when STACKTYPE="cloud" and STACKTYPE_PROVIDER="azure". Azure image to

Get list of available images using Azure CLI. e.g. az vm image list --output table. (default: Canonical:UbuntuServer:16.04-LTS:latest) ENV[AZURERESOURCEGROUP] (Optional) Only applicable, when STACKTYPE="cloud" and STACKTYPE_PROVIDER="azure". Name of Azure resource group for the instance. (default: bdb-vagrant-rg-2018-05-30) ENV[AZUREDNSPREFIX] (Optional) Only applicable, when STACKTYPE="cloud" and STACKTYPE_PROVIDER="azure". DNS Prefix of the instance. (default: bdb-instance-2018-05-30) ENV[AZUREADMINUSERNAME] (Optional) Only applicable, when STACKTYPE="cloud" and STACKTYPE_PROVIDER="azure". Admin username of the the instance. (default: vagrant) ENV[AZUREVMSIZE] (Optional) Only applicable, when STACKTYPE="cloud" and STACKTYPE_PROVIDER="azure". Azure VM size. (default: StandardD2v2) ENV[SSHPRIVATEKEY_PATH] Only required when STACKTYPE="cloud" and STACKTYPE_PROVIDER="azure". Absolute path of SSH keypair required to log into the Azure instance. -h Show this help and exit. ``` The parameter that differentiates between the deployment type is `STACK_TYPE` which currently, supports an opinionated deployment of BigchainDB on `docker`, `local` and `cloud`. This configuration deploys a docker based BigchainDB network on the dev/test machine that you are running `stack.sh` on. This is also the default `STACK_TYPE` config for `stack.sh`. Deploy a 4 node docker based BigchainDB network on your host. ```text $ export STACK_SIZE=4 $ export STACK_TYPE=docker $ export STACK_REPO=bigchaindb/bigchaindb $ export STACK_BRANCH=master $ export TM_VERSION=0.22.8 $ export MONGO_VERSION=3.6 $ bash stack.sh ``` Note: For MacOSX users, the script will not install `Docker for Mac`, it only detects if `docker` is installed on the system, if not make sure to install . Also make sure Docker API Version > 1.25. To check Docker API Version: `docker version --format '{{.Server.APIVersion}}'` This configuration deploys a VM based BigchainDB network on your host/dev. All the services are running as processes on the VMs. For `local` deployments the following dependencies must be installed i.e. Vagrant Vagrant plugins. vagrant-cachier vagrant-vbguest vagrant-hosts vagrant-azure `vagrant plugin install vagrant-cachier vagrant-vbguest vagrant-hosts vagrant-azure` Deploy a 4 node VM based BigchainDB network. ```text $ export STACK_TYPE=local $ export STACK_SIZE=4 $ export STACKVMMEMORY=2048 $ export STACKVMCPUS=1 $ export STACKBOXNAME=ubuntu/xenial64 $ export STACK_REPO=bigchaindb/bigchaindb $ export STACK_BRANCH=master $ export TM_VERSION=0.22.8 $ export MONGO_VERSION=3.6 $ bash stack.sh ``` This configuration deploys a docker based BigchainDB network on a cloud instance. Currently, only Azure is supported. For `cloud` deployments the following dependencies must be installed i.e. Vagrant Vagrant plugins. vagrant-cachier vagrant-vbguest vagrant-hosts vagrant-azure `vagrant plugin install vagrant-cachier vagrant-vbguest vagrant-hosts vagrant-azure` Deploy a 4 node docker based BigchainDB network on an Azure instance. Generate or specify an SSH keypair to login to the Azure instance. Example: ```text $ ssh-keygen -t rsa -C "<name>" -f /path/to/key/<name> ``` Configure parameters for `stack.sh` ```text $ export AZURECLIENTID=<value from azure.appId> $ export AZURETENANTID=<value from azure.tenant> $ export AZURESUBSCRIPTIONID=<your Azure subscription ID> $ export AZURECLIENTSECRET=<value from azure.password> $ export STACK_TYPE=cloud $ export STACKTYPEPROVIDER=azure $ export SSHPRIVATEKEY_PATH=</path/to/private/key> $ export AZURE_REGION=westeurope $ export AZUREIMAGEURN=Canonical:UbuntuServer:16.04-LTS:latest $ export AZURERESOURCEGROUP=bdb-vagrant-rg-2018-01-01 $ export AZUREDNSPREFIX=bdb-instance-2018-01-01 $ export AZUREADMINUSERNAME=vagrant $ export AZUREVMSIZE=StandardD2v2 $ bash stack.sh ``` Export all the variables exported for the corresponding `stack.sh` script and run `unstack.sh` to delete/remove/unstack the BigchainDB network/stack. ```text $ bash unstack.sh OR $ bash unstack.sh -s ```