bigchaindb/docs/server/source/appendices/run-with-ansible.md

Run BigchainDB with Ansible

NOT for Production Use

You can use the following instructions to deploy a single or multi node BigchainDB setup for dev/test using Ansible. Ansible will setup BigchainDB node(s) along with Docker, Docker Compose, MongoDB, BigchainDB Python driver.

Currently, this workflow is only supported for the following distributions:

• Ubuntu >= 16.04
• CentOS >= 7
• Fedora >= 24

Minimum Requirements | Ansible

Minimum resource requirements for a single node BigchainDB dev setup. The more the better:

• Memory >= 512MB
• VCPUs >= 1

Clone the BigchainDB repository | Ansible

$ git clone https://github.com/bigchaindb/bigchaindb.git

Install dependencies | Ansible

• Ansible

You can also install ansible and other dependencies, if any, using the boostrap.sh script inside the BigchainDB repository. Navigate to bigchaindb/pkg/scripts and run the bootstrap.sh script to install the dependecies for your OS. The script also checks if the OS you are running is compatible with the supported versions.

Note: bootstrap.sh only supports Ubuntu >= 16.04, CentOS >= 7 and Fedora >=24.

$ cd bigchaindb/pkg/scripts/
$ sudo ./bootstrap.sh

BigchainDB Setup Configuration(s) | Ansible

Local Setup | Ansible

You can run the Ansible playbook bdb-deploy.yml on your local dev machine and set up the BigchainDB node where BigchainDB can be run as a process or inside a Docker container(s) depending on your configuration.

Before, running the playbook locally, you need to update the hosts and bdb-config.yml configuration, which will notify Ansible that we need to run the play locally.

Update Hosts | Local

Navigate to bigchaindb/pkg/configuration/hosts inside the BigchainDB repository.

$ cd bigchaindb/pkg/configuration/hosts

Edit all configuration file:

# Delete any existing configuration in this file and insert
# Hostname of dev machine
<HOSTNAME> ansible_connection=local

Update Configuration | Local

Navigate to bigchaindb/pkg/configuration/vars inside the BigchainDB repository.

$ cd bigchaindb/pkg/configuration/vars/bdb-config.yml

Edit bdb-config.yml configuration file as per your requirements, sample configuration file(s):

---
deploy_docker: false #[true, false]
docker_cluster_size: 1 # Only needed if `deploy_docker` is true
bdb_hosts:
  - name: "<HOSTNAME>" # Hostname of dev machine

Note: You can also orchestrate a multi-node BigchainDB cluster on a local dev host using Docker containers. Here is a sample bdb-config.yml

---
deploy_docker: true #[true, false]
docker_cluster_size: 3
bdb_hosts:
  - name: "<LOCAL_DEV_HOST_HOSTNAME>"

BigchainDB Setup | Ansible

Now, You can safely run the bdb-deploy.yml playbook and everything will be taken care of by Ansible. To run the playbook please navigate to the bigchaindb/pkg/configuration directory inside the BigchainDB repository and run the bdb-deploy.yml playbook.

$ cd bigchaindb/pkg/configuration/

$ sudo ansible-playbook bdb-deploy.yml -i hosts/all

After successful execution of the playbook, you can verify that BigchainDB docker(s)/process(es) is(are) running.

Verify BigchainDB process(es):

$ ps -ef | grep bigchaindb

OR

Verify BigchainDB Docker(s):

$ docker ps | grep bigchaindb

The playbook also installs the BigchainDB Python Driver, so you can use it to make transactions and verify the functionality of your BigchainDB node. See the BigchainDB Python Driver documentation for details on how to use it.

Note: The bdb_root_url can be be one of the following:

# BigchainDB is running as a process
bdb_root_url = http://<HOST-IP>:9984

OR

# BigchainDB is running inside a docker container
bdb_root_url = http://<HOST-IP>:<DOCKER-PUBLISHED-PORT>

Note: BigchainDB has other drivers as well.

Experimental: Running Ansible a Remote Dev/Host

Remote Setup | Ansible

You can also run the Ansible playbook bdb-deploy.yml on remote machine(s) and set up the BigchainDB node where BigchainDB can run as a process or inside a Docker container(s) depending on your configuration.

Before, running the playbook on a remote host, you need to update the hosts and bdb-config.yml configuration, which will notify Ansible that we need to run the play on a remote host.

Update Hosts | Remote

Navigate to bigchaindb/pkg/configuration/hosts inside the BigchainDB repository.

$ cd bigchaindb/pkg/configuration/hosts

Edit all configuration file:

# Delete any existing configuration in this file and insert
<Remote_Host_IP/Hostname> ansible_ssh_user=<USERNAME> ansible_sudo_pass=<ROOT_PASSWORD>

Note: You can add multiple hosts to the all configuration file. Root password is needed because ansible will run some tasks that require root permissions.

Note: You can also use other methods to get inside the remote machines instead of password based SSH. For other methods please consult Ansible Documentation.

Update Configuration | Remote

Navigate to bigchaindb/pkg/configuration/vars inside the BigchainDB repository.

$ cd bigchaindb/pkg/configuration/vars/bdb-config.yml

Edit bdb-config.yml configuration file as per your requirements, sample configuration file(s):

---
deploy_docker: false #[true, false]
docker_cluster_size: 1 # Only needed if `deploy_docker` is true
bdb_hosts:
  - name: "<REMOTE_MACHINE_HOSTNAME>"

After, the configuration of remote hosts, run the Ansible playbook and verify your deployment.