mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
Merge pull request #610 from bigchaindb/docs/608/docs-clarifications-and-refactoring
Docs/608/docs clarifications and refactoring
This commit is contained in:
Troy McConaghy
GitHub
commit
c042ee570e
BIN
docs/source/_static/Node-components.png
Normal file
BIN
docs/source/_static/Node-components.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 82 KiB |
14
docs/source/cloud-deployment-starter-templates/index.rst
Normal file
14
docs/source/cloud-deployment-starter-templates/index.rst
Normal file
@ -0,0 +1,14 @@
|
||||
Cloud Deployment Starter Templates
|
||||
==================================
|
||||
|
||||
We have some "starter templates" to deploy a basic, working, but bare-bones BigchainDB node on various cloud providers. They should *not* be used as-is to deploy a node for production. They can be used as a starting point. A full production node should meet the requirements outlined in the section on :doc:`production node assumptions, components and requirements <../nodes/index>`.
|
||||
|
||||
You don't have to use the tools we use in the starter templates (e.g. Terraform and Ansible). You can use whatever tools you prefer.
|
||||
|
||||
If you find the cloud deployment starter templates for nodes helpful, then you may also be interested in our scripts for :doc:`deploying a testing cluster on AWS <../clusters-feds/aws-testing-cluster>` (documented in the Clusters & Federations section).
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
tp-node-deployment-on-aws
|
||||
tp-node-deployment-on-azure
|
||||
@ -0,0 +1,167 @@
|
||||
# Template: Node Deployment on AWS
|
||||
|
||||
If you didn't read the introduction to the [cloud deployment starter templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point.
|
||||
|
||||
The template documented on this page uses:
|
||||
|
||||
* [Terraform](https://www.terraform.io/) to provision infrastructure resources on AWS, and
|
||||
* [Ansible](https://www.ansible.com/) to manage the software and files on that infrastructure (configuration management).
|
||||
|
||||
|
||||
## Install Terraform
|
||||
|
||||
The [Terraform documentation has installation instructions](https://www.terraform.io/intro/getting-started/install.html) for all common operating systems.
|
||||
|
||||
If you don't want to run Terraform on your local machine, you can install it on a cloud machine under your control (e.g. on AWS).
|
||||
|
||||
Note: Hashicorp has an enterprise version of Terraform called "Terraform Enterprise." You can license it by itself or get it as part of Atlas. If you decide to license Terraform Enterprise or Atlas, be sure to install it on your own hosting (i.e. "on premise"), not on the hosting provided by Hashicorp. The reason is that BigchainDB clusters are supposed to be decentralized. If everyone used Hashicorp's hosted Atlas, then that would be a point of centralization.
|
||||
|
||||
**Ubuntu Installation Tips**
|
||||
|
||||
If you want to install Terraform on Ubuntu, first [download the .zip file](https://www.terraform.io/downloads.html). Then install it in `/opt`:
|
||||
```text
|
||||
sudo mkdir -p /opt/terraform
|
||||
sudo unzip path/to/zip-file.zip -d /opt/terraform
|
||||
```
|
||||
|
||||
Why install it in `/opt`? See [the answers at Ask Ubuntu](https://askubuntu.com/questions/1148/what-is-the-best-place-to-install-user-apps).
|
||||
|
||||
Next, add `/opt/terraform` to your path. If you use bash for your shell, then you could add this line to `~/.bashrc`:
|
||||
```text
|
||||
export PATH="/opt/terraform:$PATH"
|
||||
```
|
||||
|
||||
After doing that, relaunch your shell or force it to read `~/.bashrc` again, e.g. by doing `source ~/.bashrc`. You can verify that terraform is installed and in your path by doing:
|
||||
```text
|
||||
terraform --version
|
||||
```
|
||||
|
||||
It should say the current version of Terraform.
|
||||
|
||||
|
||||
## Use Terraform to Provision a One-Machine Node on AWS
|
||||
|
||||
We have an example Terraform configuration (set of files) to provision all the resources needed to run a one-machine BigchainDB node on AWS:
|
||||
|
||||
* An instance on EC2 (based on an Ubuntu 14.04 AMI)
|
||||
* A security group
|
||||
* An EBS volume
|
||||
* An elastic IP address
|
||||
|
||||
|
||||
## Get Set Up to Use Terraform
|
||||
|
||||
First, do the [basic AWS setup steps outlined in the Appendices](../appendices/aws-setup.html).
|
||||
|
||||
Then go to the `.../bigchaindb/ntools/one-m/aws/` directory and open the file `variables.tf`. Most of the variables have sensible default values, but you can change them if you like. In particular, you may want to change `aws_region`. (Terraform looks in `~/.aws/credentials` to get your AWS credentials, so you don't have to enter those anywhere.)
|
||||
|
||||
The `ssh_key_name` has no default value, so Terraform will prompt you every time it needs it.
|
||||
|
||||
To see what Terraform will do, run:
|
||||
```text
|
||||
terraform plan
|
||||
```
|
||||
|
||||
It should ask you the value of `ssh_key_name`.
|
||||
|
||||
It figured out the plan by reading all the `.tf` Terraform files in the directory.
|
||||
|
||||
If you don't want to be asked for the `ssh_key_name`, you can change the default value of `ssh_key_name` (in the file `variables.tf`) or [you can set an environmen variable](https://www.terraform.io/docs/configuration/variables.html) named `TF_VAR_ssh_key_name`.
|
||||
|
||||
|
||||
## Use Terraform to Provision Resources
|
||||
|
||||
To provision all the resources specified in the plan, do the following. **Note: This will provision actual resources on AWS, and those cost money. Be sure to shut down the resources you don't want to keep running later, otherwise the cost will keep growing.**
|
||||
```text
|
||||
terraform apply
|
||||
```
|
||||
|
||||
Terraform will report its progress as it provisions all the resources. Once it's done, you can go to the Amazon EC2 web console and see the instance, its security group, its elastic IP, and its attached storage volumes (one for the root directory and one for RethinkDB storage).
|
||||
|
||||
At this point, there is no software installed on the instance except for Ubuntu 14.04 and whatever else came with the Amazon Machine Image (AMI) specified in the Terraform configuration (files). The next step is to use Ansible to install, configure and run all the necessary software.
|
||||
|
||||
|
||||
## Optional: "Destroy" the Resources
|
||||
|
||||
If you want to shut down all the resources just provisioned, you must first disable termination protection on the instance:
|
||||
|
||||
1. Go to the EC2 console and select the instance you just launched. It should be named `BigchainDB_node`.
|
||||
2. Click **Actions** > **Instance Settings** > **Change Termination Protection** > **Yes, Disable**
|
||||
3. Back in your terminal, do `terraform destroy`
|
||||
|
||||
Terraform should "destroy" (i.e. terminate or delete) all the AWS resources you provisioned above.
|
||||
|
||||
If it fails (e.g. because of an attached and mounted EBS volume), then you can terminate the instance using the EC2 console: **Actions** > **Instance State** > **Terminate** > **Yes, Terminate**. Once the instance is terminated, you should still do `terraform destroy` to make sure that all the other resources are destroyed.
|
||||
|
||||
|
||||
## Install Ansible
|
||||
|
||||
The Ansible documentation has [installation instructions](https://docs.ansible.com/ansible/intro_installation.html). Note the control machine requirements: at the time of writing, Ansible required Python 2.6 or 2.7. (Support for Python 3 [is a goal of Ansible 2.2](https://github.com/ansible/ansible/issues/15976#issuecomment-221264089).)
|
||||
|
||||
For example, you could create a special Python 2.x virtualenv named `ansenv` and then install Ansible in it:
|
||||
```text
|
||||
cd repos/bigchaindb/ntools
|
||||
virtualenv -p /usr/local/lib/python2.7.11/bin/python ansenv
|
||||
source ansenv/bin/activate
|
||||
pip install ansible
|
||||
```
|
||||
|
||||
## About Out Example Ansible Playbook
|
||||
|
||||
We have an example Ansible playbook to install, configure and run a basic BigchainDB node on Ubuntu 14.04. It's in `.../bigchaindb/ntools/one-m/ansible/one-m-node.yml`.
|
||||
|
||||
When you run the playbook (as per the instructions below), it ensures all the necessary software is installed, configured and running. It can be used to get a BigchainDB node set up on a bare Ubuntu 14.04 machine, but it can also be used to ensure that everything is okay on a running BigchainDB node. (If you run the playbook against a host where everything is okay, then it won't change anything on that host.)
|
||||
|
||||
|
||||
## Create an Ansible Inventory File
|
||||
|
||||
An Ansible "inventory" file is a file which lists all the hosts (machines) you want to manage using Ansible. (Ansible will communicate with them via SSH.) Right now, we only want to manage one host.
|
||||
|
||||
First, determine the public IP address of the host (i.e. something like `192.0.2.128`).
|
||||
|
||||
Then create a one-line text file named `hosts` by doing this:
|
||||
```text
|
||||
# cd to the directory .../bigchaindb/ntools/one-m/ansible
|
||||
echo "192.0.2.128" > hosts
|
||||
```
|
||||
|
||||
but replace `192.0.2.128` with the IP address of the host.
|
||||
|
||||
|
||||
## Run the Ansible Playbook
|
||||
|
||||
The next step is to run the Ansible playbook named `one-m-node.yml`:
|
||||
```text
|
||||
# cd to the directory .../bigchaindb/ntools/one-m/ansible
|
||||
ansible-playbook -i hosts --private-key ~/.ssh/<key-name> one-m-node.yml
|
||||
```
|
||||
|
||||
where `<key-name>` should be replaced by the name of the SSH private key you created earlier (for SSHing to the host machine at your cloud hosting provider).
|
||||
|
||||
What did you just do? Running that playbook ensures all the software necessary for a one-machine BigchainDB node is installed, configured, and running properly. You can run that playbook on a regular schedule to ensure that the system stays properly configured. If something is okay, it does nothing; it only takes action when something is not as-desired.
|
||||
|
||||
|
||||
## Some Notes on the One-Machine Node You Just Got Running
|
||||
|
||||
* It ensures that the installed version of RethinkDB is `2.3.4~0trusty`. You can change that by changing the installation task.
|
||||
* It uses a very basic RethinkDB configuration file based on `bigchaindb/ntools/one-m/ansible/roles/rethinkdb/templates/rethinkdb.conf.j2`.
|
||||
* If you edit the RethinkDB configuration file, then running the Ansible playbook will **not** restart RethinkDB for you. You must do that manually. (You could just stop it using `sudo killall -9 rethinkdb` and then run the playbook to get it started again.)
|
||||
* It generates and uses a default BigchainDB configuration file, which is stores in `~/.bigchaindb` (the default location).
|
||||
* If you edit the BigchainDB configuration file, then running the Ansible playbook will **not* restart BigchainDB for you. You must do that manually. (You could just stop it using `sudo killall -9 bigchaindb` and then run the playbook to get it started again.)
|
||||
|
||||
|
||||
## Optional: Create an Ansible Config File
|
||||
|
||||
The above command (`ansible-playbook -i ...`) is fairly long. You can omit the optional arguments if you put their values in an [Ansible configuration file](https://docs.ansible.com/ansible/intro_configuration.html) (config file) instead. There are many places where you can put a config file, but to make one specifically for the "one-m" case, you should put it in `.../bigchaindb/ntools/one-m/ansible/`. In that directory, create a file named `ansible.cfg` with the following contents:
|
||||
```text
|
||||
[defaults]
|
||||
private_key_file = $HOME/.ssh/<key-name>
|
||||
inventory = hosts
|
||||
```
|
||||
|
||||
where, as before, `<key-name>` must be replaced.
|
||||
|
||||
|
||||
## Next Steps
|
||||
|
||||
You could make changes to the Terraform configuration and the Ansible playbook to make the node more production-worthy. See [the section on production node assumptions, components and requirements](../nodes/index.html).
|
||||
@ -0,0 +1,3 @@
|
||||
# Template: Node Deployment on Azure
|
||||
|
||||
This is a placeholder.
|
||||
@ -1,8 +1,5 @@
|
||||
.. You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
BigchainDB Clusters & Federations
|
||||
=================================
|
||||
Clusters & Federations
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
@ -1,8 +1,5 @@
|
||||
.. You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
Develop & Test BigchainDB
|
||||
=========================
|
||||
Develop & Test BigchainDB Server
|
||||
================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
@ -1,8 +1,5 @@
|
||||
.. You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
BigchainDB Drivers & Clients
|
||||
============================
|
||||
Drivers & Clients
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
@ -9,10 +9,9 @@ Table of Contents
|
||||
|
||||
introduction
|
||||
quickstart
|
||||
node-cluster-fed
|
||||
cloud-deployment-starter-templates/index
|
||||
nodes/index
|
||||
dev-and-test/index
|
||||
prod-node-depl-tplt/index
|
||||
server-reference/index
|
||||
drivers-clients/index
|
||||
clusters-feds/index
|
||||
|
||||
@ -5,16 +5,6 @@ BigchainDB is a scalable blockchain database. That is, it's a "big data" databas
|
||||
You can read about the motivations, goals and high-level architecture in the [BigchainDB whitepaper](https://www.bigchaindb.com/whitepaper/).
|
||||
|
||||
|
||||
## Setup Instructions for Various Cases
|
||||
|
||||
* [Set up a stand-alone BigchainDB node for learning and experimenting: Quickstart](quickstart.html)
|
||||
* [Set up and run a dev/test node](dev-and-test/setup-run-node.html)
|
||||
* [Deploy a testing cluster on AWS](clusters-feds/aws-testing-cluster.html)
|
||||
* [Set up and run a federation](clusters-feds/set-up-a-federation.html) (i.a. an organization with a BigchainDB cluster)
|
||||
|
||||
(Instructions for setting up a client will be provided once there's a public testnet.)
|
||||
|
||||
|
||||
## Is BigchainDB Production-Ready?
|
||||
|
||||
No, BigchainDB is not production-ready. You can use it to build a prototype or proof-of-concept (POC); many people are already doing that.
|
||||
@ -24,7 +14,40 @@ BigchainDB is currently in version 0.X. ([The Releases page on GitHub](https://g
|
||||
[The BigchainDB Roadmap](https://github.com/bigchaindb/org/blob/master/ROADMAP.md) will give you a sense of the things we intend to do with BigchainDB in the near term and the long term.
|
||||
|
||||
|
||||
## Some Basic Vocabulary
|
||||
|
||||
There is some specialized vocabulary associated with BigchainDB. To get started, you should at least know what what we mean by a BigchainDB *node*, *cluster* and *federation*.
|
||||
|
||||
A **BigchainDB node** is a machine or set of closely-linked machines running RethinkDB Server, BigchainDB Server, and related software. (A "machine" might be a bare-metal server, a virtual machine or a container.) Each node is controlled by one person or organization.
|
||||
|
||||
A set of BigchainDB nodes can connect to each other to form a **cluster**. Each node in the cluster runs the same software. A cluster contains one logical RethinkDB datastore. A cluster may have additional machines to do things such as cluster monitoring.
|
||||
|
||||
The people and organizations that run the nodes in a cluster belong to a **federation** (i.e. another organization). A federation must have some sort of governance structure to make decisions. If a cluster is run by a single company, then the federation is just that company.
|
||||
|
||||
**What's the Difference Between a Cluster and a Federation?**
|
||||
|
||||
A cluster is just a bunch of connected nodes. A federation is an organization which has a cluster, and where each node in the cluster has a different operator. Confusingly, we sometimes call a federation's cluster its "federation." You can probably tell what we mean from context.
|
||||
|
||||
There are several kinds of nodes:
|
||||
|
||||
- A **dev/test node** is a node created by a developer working on BigchainDB Server, e.g. for testing new or changed code. A dev/test node is typically run on the developer's local machine.
|
||||
|
||||
- A **bare-bones node** is a node deployed in the cloud, either as part of a testing cluster or as a starting point before upgrading the node to be production-ready. Our cloud deployment starter templates deploy a bare-bones node, as do our scripts for deploying a testing cluster on AWS.
|
||||
|
||||
- A **production node** is a node that is part of a federation's BigchainDB cluster. A production node has the most components and requirements.
|
||||
|
||||
|
||||
## Setup Instructions for Various Cases
|
||||
|
||||
* [Set up a local stand-alone BigchainDB node for learning and experimenting: Quickstart](quickstart.html)
|
||||
* [Set up and run a bare-bones node in the cloud](cloud-deployment-starter-templates/index.html)
|
||||
* [Set up and run a local dev/test node for developing and testing BigchainDB Server](dev-and-test/setup-run-node.html)
|
||||
* [Deploy a testing cluster on AWS](clusters-feds/aws-testing-cluster.html)
|
||||
* [Set up and run a federation (including production nodes)](clusters-feds/set-up-a-federation.html)
|
||||
|
||||
Instructions for setting up a client will be provided once there's a public test net.
|
||||
|
||||
|
||||
## Can I Help?
|
||||
|
||||
Yes! BigchainDB is an open-source project; we welcome contributions of all kinds. If you want to request a feature, file a bug report, make a pull request, or help in some other way, please see [the CONTRIBUTING.md file](https://github.com/bigchaindb/bigchaindb/blob/master/CONTRIBUTING.md).
|
||||
|
||||
|
||||
@ -1,13 +0,0 @@
|
||||
# Nodes, Clusters & Federations
|
||||
|
||||
A **BigchainDB node** is a machine or set of closely-linked machines running RethinkDB Server, BigchainDB Server, and related software. (A "machine" might be a bare-metal server, a virtual machine or a container.) Each node is controlled by one person or organization.
|
||||
|
||||
A set of BigchainDB nodes can connect to each other to form a **cluster**. Each node in the cluster runs the same software. A cluster contains one logical RethinkDB datastore. A cluster may have additional machines to do things such as cluster monitoring.
|
||||
|
||||
The people and organizations that run the nodes in a cluster belong to a **federation** (i.e. another organization). A federation must have some sort of governance structure to make decisions. If a cluster is run by a single company, then the federation is just that company.
|
||||
|
||||
**What's the Difference Between a Cluster and a Federation?**
|
||||
|
||||
A cluster is just a bunch of connected nodes. A federation is an organization which has a cluster, and where each node in the cluster has a different operator.
|
||||
|
||||
Confusingly, we sometimes call a federation's cluster its "federation." You can probably tell what we mean from context.
|
||||
@ -1,12 +1,10 @@
|
||||
.. You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
BigchainDB Nodes
|
||||
================
|
||||
Production Node Assumptions, Components & Requirements
|
||||
======================================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
node-assumptions
|
||||
node-components
|
||||
node-requirements
|
||||
setup-run-node
|
||||
|
||||
13
docs/source/nodes/node-assumptions.md
Normal file
13
docs/source/nodes/node-assumptions.md
Normal file
@ -0,0 +1,13 @@
|
||||
# Production Node Assumptions
|
||||
|
||||
If you're not sure what we mean by a BigchainDB *node*, *cluster*, *federation*, or *production node*, then see [the section in the Introduction where we defined those terms](../introduction.html#some-basic-vocabulary).
|
||||
|
||||
We make some assumptions about production nodes:
|
||||
|
||||
1. **Each production node is set up and managed by an experienced professional system administrator (or a team of them).**
|
||||
|
||||
2. Each production node in a federation's cluster is managed by a different person or team.
|
||||
|
||||
Because of the first assumption, we don't provide a detailed cookbook explaining how to secure a server, or other things that a sysadmin should know. (We do provide some [starter templates](../cloud-deployment-starter-templates/index.html), but those are just a starting point.)
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Node Components
|
||||
# Production Node Components
|
||||
|
||||
A BigchainDB node must include, at least:
|
||||
|
||||
@ -7,10 +7,17 @@ A BigchainDB node must include, at least:
|
||||
|
||||
When doing development and testing, it's common to install both on the same machine, but in a production environment, it may make more sense to install them on separate machines.
|
||||
|
||||
In a production environment, a BigchainDB node can have several other components, including:
|
||||
In a production environment, a BigchainDB node should have several other components, including:
|
||||
|
||||
* nginx or similar, as a reverse proxy and/or load balancer for the web server
|
||||
* nginx or similar, as a reverse proxy and/or load balancer for the Gunicorn server(s) inside the node
|
||||
* An NTP daemon running on all machines running BigchainDB code, and possibly other machines
|
||||
* A RethinkDB proxy server
|
||||
* A RethinkDB "wire protocol firewall" (in the future: this component doesn't exist yet)
|
||||
* Scalable storage for RethinkDB (e.g. using RAID)
|
||||
* Monitoring software, to monitor all the machines in the node
|
||||
* Configuration management agents (if you're using a configuration managment system that uses agents)
|
||||
* Maybe more
|
||||
|
||||
The relationship between these components is illustrated below.
|
||||
|
||||
|
||||
|
||||
@ -1,4 +1,7 @@
|
||||
# Node Requirements (OS, Memory, Storage, etc.)
|
||||
# Production Node Requirements
|
||||
|
||||
Note: This section will be broken apart into several pages, e.g. NTP requirements, RethinkDB requirements, BigchainDB requirements, etc. and those pages will add more details.
|
||||
|
||||
|
||||
## OS Requirements
|
||||
|
||||
|
||||
@ -1,8 +1,6 @@
|
||||
# Set Up and Run a Cluster Node
|
||||
|
||||
If you want to set up a BigchainDB node that's intended to be one of the nodes in a BigchainDB cluster (i.e. where each node is operated by a different member of a federation), then this page is for you, otherwise see [elsewhere](../introduction.html).
|
||||
|
||||
This is a page of general guidelines for setting up a node. It says nothing about how to upgrade software, storage, processing, etc. or other details of node management. That will be added in the future, in [the section on production node setup & management](../prod-node-depl-tplt/index.html). Once that section is more complete, this page will probably be deleted.
|
||||
This is a page of general guidelines for setting up a production node. It says nothing about how to upgrade software, storage, processing, etc. or other details of node management. It will be expanded more in the future.
|
||||
|
||||
|
||||
## Get a Server
|
||||
|
||||
@ -1,11 +0,0 @@
|
||||
Production Node Deployment Template
|
||||
===================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
overview
|
||||
install-terraform
|
||||
install-ansible
|
||||
prov-one-m-aws
|
||||
run-one-m-node
|
||||
@ -1,11 +0,0 @@
|
||||
# Install Ansible
|
||||
|
||||
The Ansible documentation has [installation instructions](https://docs.ansible.com/ansible/intro_installation.html). Note the control machine requirements: at the time of writing, Ansible required Python 2.6 or 2.7. (Support for Python 3 [is a goal of Ansible 2.2](https://github.com/ansible/ansible/issues/15976#issuecomment-221264089).)
|
||||
|
||||
For example, you could create a special Python 2.x virtualenv named `ansenv` and then install Ansible in it:
|
||||
```text
|
||||
cd repos/bigchaindb/ntools
|
||||
virtualenv -p /usr/local/lib/python2.7.11/bin/python ansenv
|
||||
source ansenv/bin/activate
|
||||
pip install ansible
|
||||
```
|
||||
@ -1,30 +0,0 @@
|
||||
# Install Terraform
|
||||
|
||||
The [Terraform documentation has installation instructions](https://www.terraform.io/intro/getting-started/install.html) for all common operating systems.
|
||||
|
||||
If you don't want to run Terraform on your local machine, you can install it on a cloud machine under your control (e.g. on AWS).
|
||||
|
||||
Note: Hashicorp has an enterprise version of Terraform called "Terraform Enterprise." You can license it by itself or get it as part of Atlas. If you decide to license Terraform Enterprise or Atlas, be sure to install it on your own hosting (i.e. "on premise"), not on the hosting provided by Hashicorp. The reason is that BigchainDB clusters are supposed to be decentralized. If everyone used Hashicorp's hosted Atlas, then that would be a point of centralization.
|
||||
|
||||
|
||||
## Ubuntu Installation Tips
|
||||
|
||||
If you want to install Terraform on Ubuntu, first [download the .zip file](https://www.terraform.io/downloads.html). Then install it in `/opt`:
|
||||
```text
|
||||
sudo mkdir -p /opt/terraform
|
||||
sudo unzip path/to/zip-file.zip -d /opt/terraform
|
||||
```
|
||||
|
||||
Why install it in `/opt`? See [the answers at Ask Ubuntu](https://askubuntu.com/questions/1148/what-is-the-best-place-to-install-user-apps).
|
||||
|
||||
Next, add `/opt/terraform` to your path. If you use bash for your shell, then you could add this line to `~/.bashrc`:
|
||||
```text
|
||||
export PATH="/opt/terraform:$PATH"
|
||||
```
|
||||
|
||||
After doing that, relaunch your shell or force it to read `~/.bashrc` again, e.g. by doing `source ~/.bashrc`. You can verify that terraform is installed and in your path by doing:
|
||||
```text
|
||||
terraform --version
|
||||
```
|
||||
|
||||
It should say the current version of Terraform.
|
||||
@ -1,14 +0,0 @@
|
||||
# Overview
|
||||
|
||||
A BigchainDB production node has more components and requirements than a dev/test node. Those are outlined in the [BigchainDB Nodes](../nodes/index.html) section.
|
||||
|
||||
You can provision and deploy a production node (to meet the requirments) using whatever tools you prefer.
|
||||
|
||||
This section documents a template (example), showing how one could use certain tools to provision and deploy a prodution node. Feel free to ignore this section or use it to help you with your preferred tools.
|
||||
|
||||
In this section, we use:
|
||||
|
||||
* [Terraform](https://www.terraform.io/) to provision infrastructure such as AWS instances, storage and security groups, and
|
||||
* [Ansible](https://www.ansible.com/) to manage the software and files on that infrastructure (configuration management).
|
||||
|
||||
If you notice something that could be done better, let us know (e.g. by creating an issue on GitHub).
|
||||
@ -1,61 +0,0 @@
|
||||
# Provision a One-Machine Node on AWS
|
||||
|
||||
We have an example Terraform configuration (set of files) to provision all the resources needed to run a one-machine BigchainDB node on AWS:
|
||||
|
||||
* An instance on EC2 (based on an Ubuntu 14.04 AMI)
|
||||
* A security group
|
||||
* An EBS volume
|
||||
* An elastic IP address
|
||||
|
||||
This page explains how to use Terraform to deploy our example Terraform configuration.
|
||||
|
||||
|
||||
## Get Set
|
||||
|
||||
First, do the [basic AWS setup steps outlined in the Appendices](../appendices/aws-setup.html).
|
||||
|
||||
Then go to the `.../bigchaindb/ntools/one-m/aws/` directory and open the file `variables.tf`. Most of the variables have sensible default values, but you can change them if you like. In particular, you may want to change `aws_region`. (Terraform looks in `~/.aws/credentials` to get your AWS credentials, so you don't have to enter those anywhere.)
|
||||
|
||||
The `ssh_key_name` has no default value, so Terraform will prompt you every time it needs it.
|
||||
|
||||
To see what Terraform will do, run:
|
||||
```text
|
||||
terraform plan
|
||||
```
|
||||
|
||||
It should ask you the value of `ssh_key_name`.
|
||||
|
||||
It figured out the plan by reading all the `.tf` Terraform files in the directory.
|
||||
|
||||
If you don't want to be asked for the `ssh_key_name`, you can change the default value of `ssh_key_name` (in the file `variables.tf`) or [you can set an environmen variable](https://www.terraform.io/docs/configuration/variables.html) named `TF_VAR_ssh_key_name`.
|
||||
|
||||
|
||||
## Provision
|
||||
|
||||
To provision all the resources specified in the plan, do the following. **Note: This will provision actual resources on AWS, and those cost money. Be sure to shut down the resources you don't want to keep running later, otherwise the cost will keep growing.**
|
||||
```text
|
||||
terraform apply
|
||||
```
|
||||
|
||||
Terraform will report its progress as it provisions all the resources. Once it's done, you can go to the Amazon EC2 web console and see the instance, its security group, its elastic IP, and its attached storage volumes (one for the root directory and one for RethinkDB storage).
|
||||
|
||||
At this point, there is no software installed on the instance except for Ubuntu 14.04 and whatever else came with the Amazon Machine Image (AMI) specified in the Terraform configuration (files). The next step is to use Ansible to install, configure and run all the necessary software.
|
||||
|
||||
|
||||
## Optional: "Destroy"
|
||||
|
||||
If you want to shut down all the resources just provisioned, you must first disable termination protection on the instance:
|
||||
|
||||
1. Go to the EC2 console and select the instance you just launched. It should be named `BigchainDB_node`.
|
||||
2. Click **Actions** > **Instance Settings** > **Change Termination Protection** > **Yes, Disable**
|
||||
3. Back in your terminal, do `terraform destroy`
|
||||
|
||||
Terraform should "destroy" (i.e. terminate or delete) all the AWS resources you provisioned above.
|
||||
|
||||
If it fails (e.g. because of an attached and mounted EBS volume), then you can terminate the instance using the EC2 console: **Actions** > **Instance State** > **Terminate** > **Yes, Terminate**. Once the instance is terminated, you should still do `terraform destroy` to make sure that all the other resources are destroyed.
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
* The [Terraform Documentation](https://www.terraform.io/docs/)
|
||||
* The [Terraform Documentation for the AWS "Provider"](https://www.terraform.io/docs/providers/aws/index.html)
|
||||
@ -1,56 +0,0 @@
|
||||
# Run a One-Machine Node
|
||||
|
||||
We have an example Ansible playbook to install, configure and run a basic BigchainDB node on Ubuntu 14.04. It's in `.../bigchaindb/ntools/one-m/ansible/one-m-node.yml`.
|
||||
|
||||
When you run the playbook (as per the instructions below), it ensures all the necessary software is installed, configured and running. It can be used to get a BigchainDB node set up on a bare Ubuntu 14.04 machine, but it can also be used to ensure that everything is okay on a running BigchainDB node. (If you run the playbook against a host where everything is okay, then it won't change anything on that host.)
|
||||
|
||||
This page explains how to use our example Ansible playbook.
|
||||
|
||||
|
||||
## Create an Ansible Inventory File
|
||||
|
||||
An Ansible "inventory" file is a file which lists all the hosts (machines) you want to manage using Ansible. (Ansible will communicate with them via SSH.) Right now, we only want to manage one host.
|
||||
|
||||
First, determine the public IP address of the host (i.e. something like `192.0.2.128`).
|
||||
|
||||
Then create a one-line text file named `hosts` by doing this:
|
||||
```text
|
||||
# cd to the directory .../bigchaindb/ntools/one-m/ansible
|
||||
echo "192.0.2.128" > hosts
|
||||
```
|
||||
|
||||
but replace `192.0.2.128` with the IP address of the host.
|
||||
|
||||
|
||||
## Run the Ansible Playbook
|
||||
|
||||
The next step is to run the Ansible playbook named `one-m-node.yml`:
|
||||
```text
|
||||
# cd to the directory .../bigchaindb/ntools/one-m/ansible
|
||||
ansible-playbook -i hosts --private-key ~/.ssh/<key-name> one-m-node.yml
|
||||
```
|
||||
|
||||
where `<key-name>` should be replaced by the name of the SSH private key you created earlier (for SSHing to the host machine at your cloud hosting provider).
|
||||
|
||||
What did you just do? Running that playbook ensures all the software necessary for a one-machine BigchainDB node is installed, configured, and running properly. You can run that playbook on a regular schedule to ensure that the system stays properly configured. If something is okay, it does nothing; it only takes action when something is not as-desired.
|
||||
|
||||
|
||||
## Some Notes on the One-Machine Node You Just Got Running
|
||||
|
||||
* It ensures that the installed version of RethinkDB is `2.3.4~0trusty`. You can change that by changing the installation task.
|
||||
* It uses a very basic RethinkDB configuration file based on `bigchaindb/ntools/one-m/ansible/roles/rethinkdb/templates/rethinkdb.conf.j2`.
|
||||
* If you edit the RethinkDB configuration file, then running the Ansible playbook will **not** restart RethinkDB for you. You must do that manually. (You could just stop it using `sudo killall -9 rethinkdb` and then run the playbook to get it started again.)
|
||||
* It generates and uses a default BigchainDB configuration file, which is stores in `~/.bigchaindb` (the default location).
|
||||
* If you edit the BigchainDB configuration file, then running the Ansible playbook will **not* restart BigchainDB for you. You must do that manually. (You could just stop it using `sudo killall -9 bigchaindb` and then run the playbook to get it started again.)
|
||||
|
||||
|
||||
## Optional: Create an Ansible Config File
|
||||
|
||||
The above command (`ansible-playbook -i ...`) is fairly long. You can omit the optional arguments if you put their values in an [Ansible configuration file](https://docs.ansible.com/ansible/intro_configuration.html) (config file) instead. There are many places where you can put a config file, but to make one specifically for the "one-m" case, you should put it in `.../bigchaindb/ntools/one-m/ansible/`. In that directory, create a file named `ansible.cfg` with the following contents:
|
||||
```text
|
||||
[defaults]
|
||||
private_key_file = $HOME/.ssh/<key-name>
|
||||
inventory = hosts
|
||||
```
|
||||
|
||||
where, as before, `<key-name>` must be replaced.
|
||||
@ -11,6 +11,11 @@ The command-line command to interact with BigchainDB is `bigchaindb`.
|
||||
Show help for the `bigchaindb` command. `bigchaindb -h` does the same thing.
|
||||
|
||||
|
||||
## bigchaindb \-\-version
|
||||
|
||||
Show the version number. `bigchaindb -v` does the same thing.
|
||||
|
||||
|
||||
## bigchaindb configure
|
||||
|
||||
Generate a local config file (which can be used to set some or all [BigchainDB node configuration settings](configuration.html)). It will auto-generate a public-private keypair and then ask you for the values of other configuration settings. If you press Enter for a value, it will use the default value.
|
||||
|
||||
@ -1,8 +1,5 @@
|
||||
.. You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
BigchainDB Settings and CLI
|
||||
===========================
|
||||
Settings & CLI
|
||||
==============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user