2018-08-16 12:31:32 +02:00
<!-- -
2020-04-06 11:52:18 +02:00
Copyright © 2020 Interplanetary Database Association e.V.,
BigchainDB and IPDB software contributors.
2018-08-16 12:31:32 +02:00
SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0)
Code is Apache-2.0 and docs are CC-BY-4.0
--->
2018-05-31 16:56:45 +02:00
# Run a BigchainDB network with Ansible
2017-09-14 14:00:13 +02:00
**NOT for Production Use**
2017-10-18 17:59:08 +02:00
You can use the following instructions to deploy a single or multi node
2018-05-31 16:56:45 +02:00
BigchainDB network for dev/test using Ansible. Ansible will configure the BigchainDB node(s).
2017-09-14 14:00:13 +02:00
Currently, this workflow is only supported for the following distributions:
- Ubuntu >= 16.04
- CentOS >= 7
- Fedora >= 24
2018-05-31 16:56:45 +02:00
- MacOSX
2017-09-14 14:00:13 +02:00
2018-05-31 16:56:45 +02:00
## Minimum Requirements
2017-10-27 17:54:19 +02:00
Minimum resource requirements for a single node BigchainDB dev setup. **The more the better** :
- Memory >= 512MB
- VCPUs >= 1
2018-05-31 16:56:45 +02:00
## Clone the BigchainDB repository
2017-09-14 14:00:13 +02:00
```text
$ git clone https://github.com/bigchaindb/bigchaindb.git
```
2018-05-31 16:56:45 +02:00
## Install dependencies
2017-09-14 14:00:13 +02:00
- [Ansible ](http://docs.ansible.com/ansible/latest/intro_installation.html )
2017-11-14 12:08:33 +01:00
You can also install `ansible` and other dependencies, if any, using the `boostrap.sh` script
2017-09-14 14:00:13 +02:00
inside the BigchainDB repository.
2018-05-31 16:56:45 +02:00
Navigate to `bigchaindb/pkg/scripts` and run the `bootstrap.sh` script to install the dependencies
2017-09-14 14:00:13 +02:00
for your OS. The script also checks if the OS you are running is compatible with the
supported versions.
2018-05-31 16:56:45 +02:00
**Note**: `bootstrap.sh` only supports Ubuntu >= 16.04, CentOS >= 7 and Fedora >=24 and MacOSX.
2017-10-18 17:59:08 +02:00
2017-09-14 14:00:13 +02:00
```text
$ cd bigchaindb/pkg/scripts/
2018-05-31 16:56:45 +02:00
$ bash bootstrap.sh --operation install
2017-09-14 14:00:13 +02:00
```
2018-05-31 16:56:45 +02:00
### BigchainDB Setup Configuration(s)
#### Local Setup
You can run the Ansible playbook `bigchaindb-start.yml` on your local dev machine and set up the BigchainDB node where
2017-11-14 12:08:33 +01:00
BigchainDB can be run as a process or inside a Docker container(s) depending on your configuration.
2017-10-18 17:59:08 +02:00
2018-05-31 16:56:45 +02:00
Before, running the playbook locally, you need to update the `hosts` and `stack-config.yml` configuration, which will notify Ansible that we need to run the play locally.
2017-09-14 14:00:13 +02:00
2018-05-31 16:56:45 +02:00
##### Update Hosts
2017-10-18 17:59:08 +02:00
Navigate to `bigchaindb/pkg/configuration/hosts` inside the BigchainDB repository.
2017-09-14 14:00:13 +02:00
```text
2017-10-18 17:59:08 +02:00
$ cd bigchaindb/pkg/configuration/hosts
```
2017-09-14 14:00:13 +02:00
2017-10-18 17:59:08 +02:00
Edit `all` configuration file:
```text
# Delete any existing configuration in this file and insert
2017-10-27 17:54:19 +02:00
# Hostname of dev machine
< HOSTNAME > ansible_connection=local
2017-10-18 17:59:08 +02:00
```
2018-05-31 16:56:45 +02:00
##### Update Configuration
2017-10-18 17:59:08 +02:00
Navigate to `bigchaindb/pkg/configuration/vars` inside the BigchainDB repository.
```text
2018-05-31 16:56:45 +02:00
$ cd bigchaindb/pkg/configuration/vars/stack-config.yml
2017-10-18 17:59:08 +02:00
```
2017-09-14 14:00:13 +02:00
2017-10-18 17:59:08 +02:00
Edit `bdb-config.yml` configuration file as per your requirements, sample configuration file(s):
```text
---
2018-05-31 16:56:45 +02:00
stack_type: "docker"
stack_size: "4"
OR
2017-10-18 17:59:08 +02:00
---
2018-05-31 16:56:45 +02:00
stack_type: "local"
stack_type: "1"
2017-10-18 17:59:08 +02:00
```
2018-05-31 16:56:45 +02:00
### BigchainDB Setup
Now, You can safely run the `bigchaindb-start.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 `bigchaindb-start.yml` playbook.
2017-10-18 17:59:08 +02:00
```text
$ cd bigchaindb/pkg/configuration/
2017-09-14 14:00:13 +02:00
2018-05-31 16:56:45 +02:00
$ ansible-playbook bigchaindb-start.yml -i hosts/all --extra-vars "operation=start home_path=$(pwd)"
2017-09-14 14:00:13 +02:00
```
2017-11-14 12:08:33 +01:00
After successful execution of the playbook, you can verify that BigchainDB docker(s)/process(es) is(are) running.
2017-09-14 14:00:13 +02:00
2017-10-18 17:59:08 +02:00
Verify BigchainDB process(es):
2017-09-14 14:00:13 +02:00
```text
$ ps -ef | grep bigchaindb
```
OR
2017-10-18 17:59:08 +02:00
Verify BigchainDB Docker(s):
2017-09-14 14:00:13 +02:00
```text
$ docker ps | grep bigchaindb
```
2018-05-31 16:56:45 +02:00
You can now send transactions and verify the functionality of your BigchainDB node.
2017-10-15 13:52:54 +02:00
See the [BigchainDB Python Driver documentation ](https://docs.bigchaindb.com/projects/py-driver/en/latest/index.html )
for details on how to use it.
2017-11-14 12:08:33 +01:00
**Note**: The `bdb_root_url` can be be one of the following:
2017-09-14 14:00:13 +02:00
```text
# 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 >
```
2017-10-15 13:52:54 +02:00
2019-01-24 14:21:21 +01:00
**Note**: BigchainDB has [other drivers as well ](http://docs.bigchaindb.com/projects/server/en/latest/drivers-clients/index.html ).
2017-11-14 12:08:33 +01:00
### Experimental: Running Ansible a Remote Dev/Host
2018-05-31 16:56:45 +02:00
#### Remote Setup
You can also run the Ansible playbook `bigchaindb-start.yml` on remote machine(s) and set up the BigchainDB node where
2017-11-14 12:08:33 +01:00
BigchainDB can run as a process or inside a Docker container(s) depending on your configuration.
2018-05-31 16:56:45 +02:00
Before, running the playbook on a remote host, you need to update the `hosts` and `stack-config.yml` configuration, which will notify Ansible that we need to run the play on a remote host.
2017-11-14 12:08:33 +01:00
2018-05-31 16:56:45 +02:00
##### Update Hosts
2017-11-14 12:08:33 +01:00
Navigate to `bigchaindb/pkg/configuration/hosts` inside the BigchainDB repository.
```text
$ cd bigchaindb/pkg/configuration/hosts
```
Edit `all` configuration file:
```text
# Delete any existing configuration in this file and insert
2018-05-31 16:56:45 +02:00
< Remote_Host_IP / Hostname > ansible_ssh_user=< USERNAME > ansible_sudo_pass=< PASSWORD >
2017-11-14 12:08:33 +01:00
```
2018-05-31 16:56:45 +02:00
**Note**: You can add multiple hosts to the `all` configuration file. Non-root user with sudo enabled password is needed because ansible will run some tasks that require those permissions.
2017-11-14 12:08:33 +01:00
**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 ](http://docs.ansible.com/ansible/latest/intro_getting_started.html ).
2018-05-31 16:56:45 +02:00
##### Update Configuration
2017-11-14 12:08:33 +01:00
Navigate to `bigchaindb/pkg/configuration/vars` inside the BigchainDB repository.
```text
2018-05-31 16:56:45 +02:00
$ cd bigchaindb/pkg/configuration/vars/stack-config.yml
2017-11-14 12:08:33 +01:00
```
2018-05-31 16:56:45 +02:00
Edit `stack-config.yml` configuration file as per your requirements, sample configuration file(s):
2017-11-14 12:08:33 +01:00
```text
---
2018-05-31 16:56:45 +02:00
stack_type: "docker"
stack_size: "4"
OR
---
stack_type: "local"
stack_type: "1"
2017-11-14 12:08:33 +01:00
```
After, the configuration of remote hosts, [run the Ansible playbook and verify your deployment ](#bigchaindb-setup-ansible ).