bigchaindb
/
bigchaindb
mirror of https://github.com/bigchaindb/bigchaindb.git
1
0
Fork 0
Code Releases Activity

Merge pull request #1945 from bigchaindb/update-some-docs-in-the-production-nodes-section 

Updated docs in the Production Nodes section for Tendermint
This commit is contained in:
vrde 2017-12-20 16:13:13 +01:00 committed by GitHub
parent 5957fa2d39 dab64485eb
commit 4c5047cb20
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 10 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/server/source/_static/Node-components.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 18 KiB

6
docs/server/source/clusters.md
View File

@ -16,10 +16,8 @@ to some extent, on the decentralization of the associated consortium. See the pa
## Relevant Technical Documentation
There are some pages and sections that will be of particular interest to anyone building or managing a BigchainDB cluster. In particular:
* [the page about how to set up and run a cluster node](production-nodes/setup-run-node.html) and
* [our production deployment template](production-deployment-template/index.html).
Anyone building or managing a BigchainDB cluster may be interested
in [our production deployment template](production-deployment-template/index.html).
## Cluster DNS Records and SSL Certificates

2
docs/server/source/production-nodes/index.rst
View File

@ -7,6 +7,4 @@ Production Nodes
node-assumptions
node-components
node-requirements
setup-run-node
reverse-proxy-notes

6
docs/server/source/production-nodes/node-assumptions.md
View File

@ -2,15 +2,13 @@
Be sure you know the key BigchainDB terminology:
* [BigchainDB node, BigchainDB cluster and BigchainDB consortum](https://docs.bigchaindb.com/en/latest/terminology.html)
* [BigchainDB node, BigchainDB cluster and BigchainDB consortium](https://docs.bigchaindb.com/en/latest/terminology.html)
* [dev/test node, bare-bones node and production node](../introduction.html)
We make some assumptions about production nodes:
1. Production nodes use MongoDB, not RethinkDB.
1. Production nodes use MongoDB (not RethinkDB, PostgreSQL, Couchbase or whatever).
1. Each production node is set up and managed by an experienced professional system administrator or a team of them.
1. Each production node in a cluster is managed by a different person or team.
You can use RethinkDB when building prototypes, but we don't advise or support using it in production.
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 templates, but those are just starting points.

5
docs/server/source/production-nodes/node-components.md
View File

@ -4,7 +4,8 @@ A production BigchainDB node must include:
* BigchainDB Server
* MongoDB Server 3.4+ (mongod)
* Scalable storage for MongoDB
* Tendermint
* Scalable storage for MongoDB and Tendermint
It could also include several other components, including:
@ -17,6 +18,6 @@ It could also include several other components, including:
* Monitoring software
* Maybe more
The relationship between the main components is illustrated below. Note that BigchainDB Server must be able to communicate with the _primary_ MongoDB instance, and any of the MongoDB instances might be the primary, so BigchainDB Server must be able to communicate with all the MongoDB instances. Also, all MongoDB instances must be able to communicate with each other.
The relationship between the main components is illustrated below.
![Components of a production node](../_static/Node-components.png)

6
docs/server/source/production-nodes/node-requirements.md
View File

@ -1,14 +1,12 @@
# Production Node Requirements
**This page is about the requirements of BigchainDB Server.** You can find the requirements of MongoDB, NGINX, your NTP daemon, your monitoring software, and other [production node components](node-components.html) in the documentation for that software.
**This page is about the requirements of BigchainDB Server.** You can find the requirements of MongoDB, Tendermint and other [production node components](node-components.html) in the documentation for that software.
## OS Requirements
BigchainDB Server requires Python 3.5+ and Python 3.5+ [will run on any modern OS](https://docs.python.org/3.5/using/index.html), but we recommend using an LTS version of [Ubuntu Server](https://www.ubuntu.com/server) or a similarly server-grade Linux distribution.
_Don't use macOS_ (formerly OS X, formerly Mac OS X), because it's not a server-grade operating system. Also, BigchaindB Server uses the Python multiprocessing package and [some functionality in the multiprocessing package doesn't work on Mac OS X](https://docs.python.org/3.5/library/multiprocessing.html#multiprocessing.Queue.qsize).
_Don't use macOS_ (formerly OS X, formerly Mac OS X), because it's not a server-grade operating system. Also, BigchaindB Server uses the Python multiprocessing package and [some functionality in the multiprocessing package doesn't work on Mac OS X](https://docs.python.org/3.6/library/multiprocessing.html#multiprocessing.Queue.qsize).
## General Considerations

23
docs/server/source/production-nodes/reverse-proxy-notes.md
View File

@ -30,7 +30,7 @@ You may also be interested in
The BigchainDB HTTP API has several endpoints,
but only one of them, the `POST /transactions` endpoint,
expects a non-empty HTTP request body:
the transaction (JSON) being submitted by the user.
the transaction being submitted by the user.
If you want to enforce a maximum-allowed transaction size
(discarding any that are larger),
@ -49,24 +49,3 @@ For more information, see
Note: By enforcing a maximum transaction size, you
[indirectly enforce a maximum crypto-conditions complexity](https://github.com/bigchaindb/bigchaindb/issues/356#issuecomment-288085251).
**Aside: Why 15 kB?**
Both [RethinkDB](https://rethinkdb.com/limitations/) and
[MongoDB have a maximum document size of 16 MB](https://docs.mongodb.com/manual/reference/limits/#limit-bson-document-size).
In BigchainDB, the biggest documents are the blocks.
A BigchainDB block can contain up to 1000 transactions,
plus some other data (e.g. the timestamp).
If we ignore the other data as negligible relative to all the transactions,
then a block of size 16 MB
will have an average transaction size of (16 MB)/1000 = 16 kB.
Therefore by limiting the max transaction size to 15 kB,
you can be fairly sure that no blocks will ever be
bigger than 16 MB.
Note: Technically, the documents that MongoDB stores aren't the JSON
that BigchainDB users think of; they're JSON converted to BSON.
Moreover, [one can use GridFS with MongoDB to store larger documents](https://docs.mongodb.com/manual/core/gridfs/).
Therefore the above calculation shoud be seen as a rough guide,
not the last word.

137
docs/server/source/production-nodes/setup-run-node.md
View File

@ -1,137 +0,0 @@
# Set Up and Run a Cluster Node
This is a page of general guidelines for setting up a production BigchainDB node. Before continuing, make sure you've read the pages about production node [assumptions](node-assumptions.html), [components](node-components.html) and [requirements](node-requirements.html).
Note: These are just guidelines. You can modify them to suit your needs. For example, if you want to initialize the MongoDB replica set before installing BigchainDB, you _can_ do that. If you'd prefer to use Docker and Kubernetes, you can (and [we have a template](../production-deployment-template/index.html)). We don't cover all possible setup procedures here.
## Security Guidelines
There are many articles, websites and books about securing servers, virtual machines, networks, etc. Consult those.
There are some [notes on BigchainDB-specific firewall setup](../appendices/firewall-notes.html) in the Appendices.
## Sync Your System Clock
A BigchainDB node uses its system clock to generate timestamps for blocks and votes, so that clock should be kept in sync with some standard clock(s). The standard way to do that is to run an NTP daemon (Network Time Protocol daemon) on the node.
MongoDB also recommends having an NTP daemon running on all MongoDB nodes.
NTP is a standard protocol. There are many NTP daemons implementing it. We don't recommend a particular one. On the contrary, we recommend that different nodes in a cluster run different NTP daemons, so that a problem with one daemon won't affect all nodes.
Please see the [notes on NTP daemon setup](../appendices/ntp-notes.html) in the Appendices.
## Set Up Storage for MongoDB
We suggest you set up a separate storage device (partition, RAID array, or logical volume) to store the data in the MongoDB database. Here are some questions to ask:
* How easy will it be to add storage in the future? Will I have to shut down my server?
* How big can the storage get? (Remember that [RAID](https://en.wikipedia.org/wiki/RAID) can be used to make several physical drives look like one.)
* How fast can it read & write data? How many input/output operations per second (IOPS)?
* How does IOPS scale as more physical hard drives are added?
* What's the latency?
* What's the reliability? Is there replication?
* What's in the Service Level Agreement (SLA), if applicable?
* What's the cost?
There are many options and tradeoffs.
Consult the MongoDB documentation for its recommendations regarding storage hardware, software and settings, e.g. in the [MongoDB Production Notes](https://docs.mongodb.com/manual/administration/production-notes/).
## Install and Run MongoDB
* [Install MongoDB 3.4+](https://docs.mongodb.com/manual/installation/). (BigchainDB only works with MongoDB 3.4+.)
* [Run MongoDB (mongod)](https://docs.mongodb.com/manual/reference/program/mongod/)
## Install BigchainDB Server
### Install BigchainDB Server Dependencies
Before you can install BigchainDB Server, you must [install its OS-level dependencies](../appendices/install-os-level-deps.html) and you may have to [install Python 3.5+](https://www.python.org/downloads/).
### How to Install BigchainDB Server with pip
BigchainDB is distributed as a Python package on PyPI so you can install it using `pip`. First, make sure you have an up-to-date Python 3.5+ version of `pip` installed:
```text
pip -V
```
If it says that `pip` isn't installed, or it says `pip` is associated with a Python version less than 3.5, then you must install a `pip` version associated with Python 3.5+. In the following instructions, we call it `pip3` but you may be able to use `pip` if that refers to the same thing. See [the `pip` installation instructions](https://pip.pypa.io/en/stable/installing/).
On Ubuntu 16.04, we found that this works:
```text
sudo apt-get install python3-pip
```
That should install a Python 3 version of `pip` named `pip3`. If that didn't work, then another way to get `pip3` is to do `sudo apt-get install python3-setuptools` followed by `sudo easy_install3 pip`.
You can upgrade `pip` (`pip3`) and `setuptools` to the latest versions using:
```text
pip3 install --upgrade pip setuptools
pip3 -V
```
Now you can install BigchainDB Server using:
```text
pip3 install bigchaindb
```
(If you're not in a virtualenv and you want to install bigchaindb system-wide, then put `sudo` in front.)
Note: You can use `pip3` to upgrade the `bigchaindb` package to the latest version using `pip3 install --upgrade bigchaindb`.
### How to Install BigchainDB Server from Source
If you want to install BitchainDB from source because you want to use the very latest bleeding-edge code, clone the public repository:
```text
git clone git@github.com:bigchaindb/bigchaindb.git
cd bigchaindb
python setup.py install
```
## Configure BigchainDB Server
Start by creating a default BigchainDB config file for a MongoDB backend:
```text
bigchaindb -y configure mongodb
```
(There's documentation for the `bigchaindb` command is in the section on [the BigchainDB Command Line Interface (CLI)](../server-reference/bigchaindb-cli.html).)
Edit the created config file by opening `$HOME/.bigchaindb` (the created config file) in your text editor:
* Change `"server": {"bind": "localhost:9984", ... }` to `"server": {"bind": "0.0.0.0:9984", ... }`. This makes it so traffic can come from any IP address to port 9984 (the HTTP Client-Server API port).
* Change `"keyring": []` to `"keyring": ["public_key_of_other_node_A", "public_key_of_other_node_B", "..."]` i.e. a list of the public keys of all the other nodes in the cluster. The keyring should _not_ include your node's public key.
* Ensure that `database.host` and `database.port` are set to the hostname and port of your MongoDB instance. (The port is usually 27017, unless you changed it.)
For more information about the BigchainDB config file, see the page about the [BigchainDB configuration settings](../server-reference/configuration.html).
## Get All Other Nodes to Update Their Keyring
All other BigchainDB nodes in the cluster must add your new node's public key to their BigchainDB keyring. Currently, the only way to get BigchainDB Server to "notice" a changed keyring is to shut it down and start it back up again (with the new keyring).
## Maybe Update the MongoDB Replica Set
**If this isn't the first node in the BigchainDB cluster**, then someone with an existing BigchainDB node (not you) must add your MongoDB instance to the MongoDB replica set. They can do so (on their node) using:
```text
bigchaindb add-replicas your-mongod-hostname:27017
```
where they must replace `your-mongod-hostname` with the actual hostname of your MongoDB instance, and they may have to replace `27017` with the actual port.
## Start BigchainDB
**Warning: If you're not deploying the first node in the BigchainDB cluster, then don't start BigchainDB before your MongoDB instance has been added to the MongoDB replica set (as outlined above).**
```text
# See warning above
bigchaindb start
```