mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
Merge pull request #388 from bigchaindb/feat/331/docs-on-federations
Feat/331/docs on federations
This commit is contained in:
Troy McConaghy
GitHub
commit
103e3f85e9
@ -13,9 +13,9 @@ A scalable blockchain database. [The whitepaper](https://www.bigchaindb.com/whit
|
||||
|
||||
## Quick Start
|
||||
|
||||
### [Install and Run BigchainDB Server](http://bigchaindb.readthedocs.io/en/latest/servers/installing-server.html)
|
||||
### [Run BigchainDB with Docker](http://bigchaindb.readthedocs.io/en/latest/installing-server.html#run-bigchaindb-with-docker)
|
||||
### [The Python Server API by Example](http://bigchaindb.readthedocs.io/en/latest/servers/python-server-api-examples.html)
|
||||
### [Set Up and Run a BigchainDB Node](http://bigchaindb.readthedocs.io/en/latest/nodes/setup-run-node.html)
|
||||
### [Run BigchainDB with Docker](http://bigchaindb.readthedocs.io/en/latest/nodes/run-with-docker.html)
|
||||
### [The Python Server API by Example](http://bigchaindb.readthedocs.io/en/latest/nodes/python-server-api-examples.html)
|
||||
### [The Python Driver API by Example](http://bigchaindb.readthedocs.io/en/latest/drivers-clients/python-driver-api-examples.html)
|
||||
|
||||
## Links for Everyone
|
||||
|
||||
@ -1,17 +0,0 @@
|
||||
# Glossary of Terms
|
||||
|
||||
**BigchaindB client.** A computer that can communicate with a BigchainDB cluster via the BigchainDB client-server API.
|
||||
|
||||
**BigchainDB cluster.** A collection of servers running BigchainDB Server software and communicating with each other via RethinkDB protocols. a BigchainDB cluster contains one logical RethinkDB datastore.
|
||||
|
||||
**Block.** A collection of up to 1000 transactions, plus other things. They get chained together by votes. See [the section on the block model](../topic-guides/models.html#the-block-model).
|
||||
|
||||
**Federation.** 1. An organization with members and some kind of governance structure. 2. The BigchainDB cluster owned and operated by a Federation's members.
|
||||
|
||||
**Federation node.** A server running BigchainDB Server software, with permission to communicate with other nodes in a federation.
|
||||
|
||||
**Node.** See _Federation node_.
|
||||
|
||||
**Transaction.** The basic informational unit. A transaction can represent the creation or transfer of a digital asset. See [the section on the transaction model](../topic-guides/models.html#the-transaction-model).
|
||||
|
||||
**Vote.** Each federation node in a federation is required to vote on the validity of every block (i.e. whether the block valid or not). A node's vote on a block also includes the id of the block it considers to be the previous block. See [the section on the vote model](../topic-guides/models.html#the-vote-model).
|
||||
@ -7,10 +7,10 @@ Appendices
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
glossary
|
||||
json-serialization
|
||||
cryptography
|
||||
the-Bigchain-class
|
||||
consensus
|
||||
ntp-notes
|
||||
local-rethinkdb-cluster
|
||||
licenses
|
||||
@ -4,7 +4,7 @@ This section explains one way to deploy a multi-node RethinkDB cluster on one ma
|
||||
|
||||
## Launching More RethinkDB Nodes
|
||||
|
||||
Assuming you've already [installed RethinkDB](../servers/installing-server.html#install-and-run-rethinkdb-server) and have one RethinkDB node running, here's how you can launch two more nodes on the same machine. First, prepare two additional nodes. Note that the user who starts RethinkDB must have write access to the created directories:
|
||||
Assuming you've already [installed RethinkDB](../nodes/setup-run-node.html#install-and-run-rethinkdb-server) and have one RethinkDB node running, here's how you can launch two more nodes on the same machine. First, prepare two additional nodes. Note that the user who starts RethinkDB must have write access to the created directories:
|
||||
|
||||
mkdir -p /path/to/node2
|
||||
mkdir -p /path/to/node3
|
||||
|
||||
41
docs/source/appendices/ntp-notes.md
Normal file
41
docs/source/appendices/ntp-notes.md
Normal file
@ -0,0 +1,41 @@
|
||||
# Notes on NTP Daemon Setup
|
||||
|
||||
As mentioned [elsewhere in these docs](../nodes/setup-run-node.html), there are several NTP daemons available, including:
|
||||
|
||||
* The reference NTP daemon from ntp.org; see [their support website](http://support.ntp.org/bin/view/Support/WebHome)
|
||||
* [OpenNTPD](http://www.openntpd.org/)
|
||||
* [chrony](https://chrony.tuxfamily.org/index.html)
|
||||
* Maybe [NTPsec](https://www.ntpsec.org/), once it's production-ready
|
||||
* Maybe [Ntimed](http://nwtime.org/projects/ntimed/), once it's production-ready
|
||||
* [More](https://en.wikipedia.org/wiki/Ntpd#Implementations)
|
||||
|
||||
It's tricky to make an NTP daemon setup secure. Always install the latest version and read the documentation about how to configure and run it securely.
|
||||
|
||||
|
||||
## Ubuntu Packages
|
||||
|
||||
The [Ubuntu 14.04 (Trusty Tahr) package `ntp`](https://launchpad.net/ubuntu/trusty/+source/ntp) is based on the reference implementation of an NTP daemon.
|
||||
|
||||
The following commands will uninstall the `ntp` and `ntpdate` packages, install the latest `ntp` package (which _might not be based on the latest ntpd code_), and start the NTP daemon (a local NTP server). (`ntpdate` is not reinstalled because it's [deprecated](https://askubuntu.com/questions/297560/ntpd-vs-ntpdate-pros-and-cons) and you shouldn't use it.)
|
||||
```text
|
||||
sudo apt-get --purge remove ntp ntpdate
|
||||
sudo apt-get autoremove
|
||||
sudo apt-get update
|
||||
sudo apt-get install ntp
|
||||
# That should start the NTP daemon too, but just to be sure:
|
||||
sudo service ntp restart
|
||||
```
|
||||
|
||||
You can check if NTP is running using `sudo ntpq -p`.
|
||||
|
||||
You may want to use different NTP time servers. You can change them by editing the NTP config file `/etc/ntp.conf`.
|
||||
|
||||
Note: A server running the NTP daemon can be used by others for DRDoS amplification attacks. The above installation procedure should install a default NTP configuration file `/etc/ntp.conf` with the lines:
|
||||
```text
|
||||
restrict -4 default kod notrap nomodify nopeer noquery
|
||||
restrict -6 default kod notrap nomodify nopeer noquery
|
||||
```
|
||||
|
||||
Those lines should prevent the NTP daemon from being used in an attack. (The first line is for IPv4, the second for IPv6.)
|
||||
|
||||
There are additional things you can do to make NTP more secure. See the [NTP Support Website](http://support.ntp.org/bin/view/Support/WebHome) for more details.
|
||||
@ -124,7 +124,7 @@ fab --fabfile=fabfile-monitor.py --hosts=<EC2 hostname> run_monitor
|
||||
|
||||
For more information about monitoring (e.g. how to view the Grafana dashboard in your web browser), see the [Monitoring](monitoring.html) section of this documentation.
|
||||
|
||||
To configure a BigchainDB node to send monitoring data to the monitoring server, change the statsd host in the configuration of the BigchainDB node. The section on [Configuring a BigchainDB Node](configuration.html) explains how you can do that. (For example, you can change the statsd host in `$HOME/.bigchaindb`.)
|
||||
To configure a BigchainDB node to send monitoring data to the monitoring server, change the statsd host in the configuration of the BigchainDB node. The section on [Configuring a BigchainDB Node](../nodes/configuration.html) explains how you can do that. (For example, you can change the statsd host in `$HOME/.bigchaindb`.)
|
||||
|
||||
|
||||
## Deploy a BigchainDB Cluster
|
||||
40
docs/source/clusters-feds/federation-set-up.md
Normal file
40
docs/source/clusters-feds/federation-set-up.md
Normal file
@ -0,0 +1,40 @@
|
||||
# Set Up and Run a Federation
|
||||
|
||||
This section is about how to set up and run a BigchainDB _federation_, where each node is operated by a different operator. If you want to set up and run a BigchainDB cluster on AWS (where all nodes are operated by you), then see [the section about that](deploy-on-aws.html).
|
||||
|
||||
|
||||
## Initial Checklist
|
||||
|
||||
* Do you have a governance process for making federation-level decisions, such as how to admit new members?
|
||||
* What will you store in creation transactions (data payload)? Is there a data schema?
|
||||
* Will you use transfer transactions? Will they include a non-empty data payload?
|
||||
* Who will be allowed to submit transactions? Who will be allowed to read or query transactions? How will you enforce the access rules?
|
||||
|
||||
|
||||
## Set Up the Initial Cluster
|
||||
|
||||
When you first start a federation cluster, the initial nodes will all start at roughly the same time.
|
||||
|
||||
The steps to set up a cluster node are outlined in the section titled [Set Up and Run a Node](../nodes/setup-run-node.html). You'll need two pieces of information from all other nodes in the federation:
|
||||
|
||||
1. Their RethinkDB hostname, e.g. `rdb.farm2.organization.org`
|
||||
2. Their BigchainDB public key, e.g. `Eky3nkbxDTMgkmiJC8i5hKyVFiAQNmPP4a2G4JdDxJCK`
|
||||
|
||||
One node must be chosen as the "designated fist node": they must run some RethinkDB configuration commands after all nodes have started RethinkDB, but before any node has started BigchainDB.
|
||||
|
||||
|
||||
## Documentation to Come
|
||||
|
||||
* Backing Up & Restoring data
|
||||
* Adding a node (including resharding etc.)
|
||||
* Removing a node
|
||||
* Logging
|
||||
* Node monitoring & crash recovery
|
||||
* Node Security
|
||||
* Securing your OS
|
||||
* Firewalls and security groups. Remember to open port 123 for NTP.
|
||||
* (Private) key management
|
||||
* RethinkDB security
|
||||
* Cluster monitoring
|
||||
* Internal watchdogs
|
||||
* External watchdogs
|
||||
13
docs/source/clusters-feds/index.rst
Normal file
13
docs/source/clusters-feds/index.rst
Normal file
@ -0,0 +1,13 @@
|
||||
.. You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
BigchainDB Clusters & Federations
|
||||
=================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
federation-set-up
|
||||
deploy-on-aws
|
||||
monitoring
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Monitoring
|
||||
# Cluster Monitoring
|
||||
|
||||
BigchainDB uses [StatsD](https://github.com/etsy/statsd) for monitoring. We require some additional infrastructure to take full advantage of its functionality:
|
||||
BigchainDB uses [StatsD](https://github.com/etsy/statsd) for cluster monitoring. We require some additional infrastructure to take full advantage of its functionality:
|
||||
|
||||
* an agent to listen for metrics: [Telegraf](https://github.com/influxdata/telegraf),
|
||||
* a time-series database: [InfluxDB](https://influxdata.com/time-series-platform/influxdb/), and
|
||||
@ -28,7 +28,7 @@ You can view the Grafana dashboard in your web browser at:
|
||||
|
||||
(You may want to replace `localhost` with another hostname in that URL, e.g. the hostname of a remote monitoring server.)
|
||||
|
||||
The login and password are `admin` by default. If BigchainDB is running and processing transactions, you should see analytics—if not, [start BigchainDB](installing-server.html#run-bigchaindb) and load some test transactions:
|
||||
The login and password are `admin` by default. If BigchainDB is running and processing transactions, you should see analytics—if not, [start BigchainDB](../nodes/setup-run-node.html#run-bigchaindb) and load some test transactions:
|
||||
```text
|
||||
$ bigchaindb load
|
||||
```
|
||||
@ -12,7 +12,8 @@ Table of Contents
|
||||
|
||||
introduction
|
||||
topic-guides/index
|
||||
servers/index
|
||||
nodes/index
|
||||
clusters-feds/index
|
||||
drivers-clients/index
|
||||
release-notes
|
||||
appendices/index
|
||||
|
||||
@ -1,23 +1,13 @@
|
||||
# Introduction
|
||||
|
||||
BigchainDB is a scalable blockchain database. That is, it's a "big data" database with some blockchain characteristics, including decentralization, immutability and native support for assets.
|
||||
BigchainDB is a scalable blockchain database. That is, it's a "big data" database with some blockchain characteristics, including [decentralization](topic-guides/decentralized.html), [immutability](topic-guides/immutable.html) and [native support for assets](topic-guides/assets.html).
|
||||
|
||||
You can read about the motivations, goals and high-level architecture in the [BigchainDB whitepaper](https://www.bigchaindb.com/whitepaper/).
|
||||
|
||||
|
||||
## Who this Documentation for?
|
||||
|
||||
The BigchainDB Documentation is intended primarily for:
|
||||
|
||||
1. Developers of BigchainDB server software.
|
||||
2. People deploying and managing BigchainDB clusters.
|
||||
3. Developers of BigchainDB driver software (SDKs used to develop client software).
|
||||
4. App developers who are developing client apps to talk to one or more live, operational BigchainDB clusters. They would use one of the BigchainDB drivers.
|
||||
|
||||
|
||||
## 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. Please don't use it for something mission-critical.
|
||||
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.
|
||||
|
||||
BigchainDB is currently in version 0.X. ([The Releases page on GitHub](https://github.com/bigchaindb/bigchaindb/releases) has the exact version number.) Once we believe that BigchainDB is production-ready, we'll release version 1.0.
|
||||
|
||||
|
||||
@ -60,7 +60,7 @@ environment variables available are:
|
||||
- `BIGCHAINDB_KEYPAIR_PUBLIC` defines the public key of the BigchainDB node.
|
||||
- `BIGCHAINDB_KEYPAIR_PRIVATE` defines the private key of the BigchainDB node.
|
||||
- `BIGCHAINDB_KEYRING` is a colon-separated list of the public keys of all _other_ nodes in the cluster.
|
||||
- `BIGCHAINDB_STATSD_HOST` defines the hostname of the statsd server for [monitoring](monitoring.html).
|
||||
- `BIGCHAINDB_STATSD_HOST` defines the hostname of the statsd server for [monitoring](../clusters-feds/monitoring.html).
|
||||
- `BIGCHAINDB_STATSD_PORT` defines the port of the statsd server for monitoring.
|
||||
- `BIGCHAINDB_STATSD_RATE` is a float between `0` and `1` that defines the fraction of transaction operations sampled.
|
||||
- `BIGCHAINDB_API_ENDPOINT` defines the API endpoint to use (e.g. `http://localhost:9984/api/v1`).
|
||||
@ -1,16 +1,16 @@
|
||||
.. You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
BigchainDB Servers (Nodes) & Clusters
|
||||
=====================================
|
||||
BigchainDB Nodes
|
||||
================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
installing-server
|
||||
node-requirements
|
||||
setup-run-node
|
||||
run-with-docker
|
||||
running-unit-tests
|
||||
configuration
|
||||
bigchaindb-cli
|
||||
python-server-api-examples
|
||||
deploy-on-aws
|
||||
monitoring
|
||||
47
docs/source/nodes/node-requirements.md
Normal file
47
docs/source/nodes/node-requirements.md
Normal file
@ -0,0 +1,47 @@
|
||||
# Node Requirements (OS, Memory, Storage, etc.)
|
||||
|
||||
For now, we will assume that a BigchainDB node is just one server. In the future, a node may consist of several closely-coupled servers run by one node operator (federation member).
|
||||
|
||||
|
||||
## OS Requirements
|
||||
|
||||
* RethinkDB Server [will run on any modern OS](https://www.rethinkdb.com/docs/install/). Note that the Fedora package isn't officially supported. Also, official support for Windows is fairly recent ([April 2016](https://rethinkdb.com/blog/2.3-release/)).
|
||||
* Python 3.4+ [will run on any modern OS](https://docs.python.org/3.4/using/index.html).
|
||||
* [Some functionality in the `multiprocessing` package doesn't work on OS X](https://docs.python.org/3.4/library/multiprocessing.html#multiprocessing.Queue.qsize). You can still use Mac OS X if you use Docker or a virtual machine.
|
||||
* ZeroMQ [will run on any modern OS](http://zeromq.org/area:download).
|
||||
|
||||
The BigchainDB core dev team uses Ubuntu 14.04 or Fedora 23.
|
||||
|
||||
We don't test BigchainDB on Windows or Mac OS X, but you can try.
|
||||
|
||||
* If you run into problems on Windows, then you may want to try using Vagrant. One of our community members ([@Mec-Is](https://github.com/Mec-iS)) wrote [a page about how to install BigchainDB on a VM with Vagrant](https://gist.github.com/Mec-iS/b84758397f1b21f21700).
|
||||
* If you have Mac OS X and want to experiment with BigchainDB, then you could do that [using Docker](run-with-docker.html).
|
||||
|
||||
|
||||
## Memory Requirements
|
||||
|
||||
Every OS has memory requirements; check the memory requirements of your OS.
|
||||
|
||||
There is [documentation about RethinkDB's memory requirements](https://rethinkdb.com/docs/memory-usage/). In particular: "RethinkDB requires data structures in RAM on each server proportional to the size of the data on that server’s disk, usually around 1% of the size of the total data set." ([source](https://rethinkdb.com/limitations/))
|
||||
|
||||
|
||||
## Storage Requirements
|
||||
|
||||
If you want a RethinkDB cluster to store an amount of data D, with a replication factor of R (on every table), and the cluster has N nodes, then each node will need to be able to store R×D/N data plus the storage required for the OS and various other software (RethinkDB, Python, etc.). The secondary indexes also require some storage.
|
||||
|
||||
For failover to work, [every RethinkDB table must have at least three replicas](https://rethinkdb.com/docs/failover/), i.e. R ≥ 3.
|
||||
|
||||
Also, RethinkDB tables can have [at most 64 shards](https://rethinkdb.com/limitations/). For example, if you have only one table and more than 64 nodes, some nodes won't have the primary of any shard, i.e. they will have replicas only. In other words, once you pass 64 nodes, adding more nodes won't provide storage space for new data; it will only add more space for shard replicas. If the biggest single-node storage available is d, then the most you can store in a RethinkDB cluster is < 64×d: accomplished by putting one primary shard in each of 64 nodes, with all replica shards on other nodes. (This is assuming one table. If there are T tables, then the most you can store is < 64×d×T.)
|
||||
|
||||
|
||||
## Compatible File Systems
|
||||
|
||||
RethinkDB has [issues with `btrfs`](https://github.com/rethinkdb/rethinkdb/issues/2781) (B-tree file system).
|
||||
|
||||
It's best to have a file system that supports direct I/O, because that will improve RethinkDB performance. Many compressed or encrypted file systems don't support direct I/O.
|
||||
|
||||
|
||||
## CPU Requirements
|
||||
|
||||
Most servers will have enough CPUs (or vCPUs) to run a BigchainDB node. The more you have, the higher throughput will be.
|
||||
|
||||
@ -8,7 +8,7 @@ We create a digital asset, sign it, write it to a BigchainDB Server instance, re
|
||||
|
||||
## Getting Started
|
||||
|
||||
First, make sure you have RethinkDB and BigchainDB _installed and running_, i.e. you [installed them](installing-server.html) and you ran:
|
||||
First, make sure you have RethinkDB and BigchainDB _installed and running_, i.e. you [installed them](setup-run-node.html) and you ran:
|
||||
```text
|
||||
$ rethinkdb
|
||||
$ bigchaindb configure
|
||||
120
docs/source/nodes/run-with-docker.md
Normal file
120
docs/source/nodes/run-with-docker.md
Normal file
@ -0,0 +1,120 @@
|
||||
# Run BigchainDB with Docker
|
||||
|
||||
**NOT for Production Use**
|
||||
|
||||
For those who like using Docker and wish to experiment with BigchainDB in
|
||||
non-production environments, we currently maintain a Docker image and a
|
||||
`Dockerfile` that can be used to build an image for `bigchaindb`.
|
||||
|
||||
## Pull and Run the Image from Docker Hub
|
||||
|
||||
Assuming you have Docker installed, you would proceed as follows.
|
||||
|
||||
In a terminal shell, pull the latest version of the BigchainDB Docker image using:
|
||||
```text
|
||||
docker pull bigchaindb/bigchaindb
|
||||
```
|
||||
|
||||
then do a one-time configuration step to create the config file; we will use
|
||||
the `-y` option to accept all the default values. The configuration file will
|
||||
be stored in a file on your host machine at `~/bigchaindb_docker/.bigchaindb`:
|
||||
|
||||
```text
|
||||
docker run --rm -v "$HOME/bigchaindb_docker:/data" -ti \
|
||||
bigchaindb/bigchaindb -y configure
|
||||
Generating keypair
|
||||
Configuration written to /data/.bigchaindb
|
||||
Ready to go!
|
||||
```
|
||||
|
||||
Let's analyze that command:
|
||||
|
||||
* `docker run` tells Docker to run some image
|
||||
* `--rm` remove the container once we are done
|
||||
* `-v "$HOME/bigchaindb_docker:/data"` map the host directory
|
||||
`$HOME/bigchaindb_docker` to the container directory `/data`;
|
||||
this allows us to have the data persisted on the host machine,
|
||||
you can read more in the [official Docker
|
||||
documentation](https://docs.docker.com/engine/userguide/containers/dockervolumes/#mount-a-host-directory-as-a-data-volume)
|
||||
* `-t` allocate a pseudo-TTY
|
||||
* `-i` keep STDIN open even if not attached
|
||||
* `bigchaindb/bigchaindb the image to use
|
||||
* `-y configure` execute the `configure` sub-command (of the `bigchaindb` command) inside the container, with the `-y` option to automatically use all the default config values
|
||||
|
||||
|
||||
After configuring the system, you can run BigchainDB with the following command:
|
||||
|
||||
```text
|
||||
docker run -v "$HOME/bigchaindb_docker:/data" -d \
|
||||
--name bigchaindb \
|
||||
-p "58080:8080" -p "59984:9984" \
|
||||
bigchaindb/bigchaindb start
|
||||
```
|
||||
|
||||
The command is slightly different from the previous one, the differences are:
|
||||
|
||||
* `-d` run the container in the background
|
||||
* `--name bigchaindb` give a nice name to the container so it's easier to
|
||||
refer to it later
|
||||
* `-p "58080:8080"` map the host port `58080` to the container port `8080`
|
||||
(the RethinkDB admin interface)
|
||||
* `-p "59984:9984"` map the host port `59984` to the container port `9984`
|
||||
(the BigchainDB API server)
|
||||
* `start` start the BigchainDB service
|
||||
|
||||
Another way to publish the ports exposed by the container is to use the `-P` (or
|
||||
`--publish-all`) option. This will publish all exposed ports to random ports. You can
|
||||
always run `docker ps` to check the random mapping.
|
||||
|
||||
You can also access the RethinkDB dashboard at
|
||||
[http://localhost:58080/](http://localhost:58080/)
|
||||
|
||||
If that doesn't work, then replace `localhost` with the IP or hostname of the
|
||||
machine running the Docker engine. If you are running docker-machine (e.g. on
|
||||
Mac OS X) this will be the IP of the Docker machine (`docker-machine ip
|
||||
machine_name`).
|
||||
|
||||
### Load Testing with Docker
|
||||
|
||||
Now that we have BigchainDB running in the Docker container named `bigchaindb`, we can
|
||||
start another BigchainDB container to generate a load test for it.
|
||||
|
||||
First, make sure the container named `bigchaindb` is still running. You can check that using:
|
||||
```text
|
||||
docker ps
|
||||
```
|
||||
|
||||
You should see a container named `bigchaindb` in the list.
|
||||
|
||||
You can load test the BigchainDB running in that container by running the `bigchaindb load` command in a second container:
|
||||
|
||||
```text
|
||||
docker run --rm -v "$HOME/bigchaindb_docker:/data" -ti \
|
||||
--link bigchaindb \
|
||||
bigchaindb/bigchaindb load
|
||||
```
|
||||
|
||||
Note the `--link` option to link to the first container (named `bigchaindb`).
|
||||
|
||||
Aside: The `bigchaindb load` command has several options (e.g. `-m`). You can read more about it in [the documentation about the BigchainDB command line interface](bigchaindb-cli.html).
|
||||
|
||||
If you look at the RethinkDB dashboard (in your web browser), you should see the effects of the load test. You can also see some effects in the Docker logs using:
|
||||
```text
|
||||
docker logs -f bigchaindb
|
||||
```
|
||||
|
||||
## Building Your Own Image
|
||||
|
||||
Assuming you have Docker installed, you would proceed as follows.
|
||||
|
||||
In a terminal shell:
|
||||
```text
|
||||
git clone git@github.com:bigchaindb/bigchaindb.git
|
||||
```
|
||||
|
||||
Build the Docker image:
|
||||
```text
|
||||
docker build --tag local-bigchaindb .
|
||||
```
|
||||
|
||||
Now you can use your own image to run BigchainDB containers.
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
Once you've installed BigchainDB Server, you may want to run all the unit tests. This section explains how.
|
||||
|
||||
First of all, if you installed BigchainDB Server using `pip` (i.e. by getting the package from PyPI), then you didn't install the tests. **Before you can run all the unit tests, you must [install BigchainDB from source](installing-server.html#how-to-install-bigchaindb-from-source).**
|
||||
First of all, if you installed BigchainDB Server using `pip` (i.e. by getting the package from PyPI), then you didn't install the tests. **Before you can run all the unit tests, you must [install BigchainDB from source](setup-run-node.html#how-to-install-bigchaindb-from-source).**
|
||||
|
||||
To run all the unit tests, first make sure you have RethinkDB running:
|
||||
|
||||
229
docs/source/nodes/setup-run-node.md
Normal file
229
docs/source/nodes/setup-run-node.md
Normal file
@ -0,0 +1,229 @@
|
||||
# Set Up and Run a Node
|
||||
|
||||
This section goes through the steps to set up a BigchainDB node (running RethinkDB Server, BigchainDB Server, etc.). There are instructions for two cases:
|
||||
|
||||
1. Stand-Alone Node (useful for local testing and development)
|
||||
2. Cluster Node
|
||||
|
||||
|
||||
## Get a Server
|
||||
|
||||
The first step is to get a server (or equivalent) which meets [the requirements for a BigchainDB node](node-requirements.html).
|
||||
|
||||
|
||||
## Secure Your Server
|
||||
|
||||
The steps that you must take to secure your server depend on your server OS and where your server is physically located. There are many articles and books about how to secure a server. Ask a search engine.
|
||||
|
||||
Here we just cover special considerations when securing a BigchainDB node.
|
||||
|
||||
TODO: Special security considerations for BigchainDB nodes.
|
||||
|
||||
TODO: Notes about firewall setup. What ports should be open, for what kinds of traffic, accepting connections from what IP addresses, etc. For example, NTP uses port 123. Can firewall setup be done now or does it have to happen later?
|
||||
|
||||
|
||||
## Sync Your System Clock
|
||||
|
||||
If you're just setting up a stand-alone node, then you can skip this step.
|
||||
|
||||
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. (You could also use tlsdate, which uses TLS timestamps rather than NTP, but don't: it's not very accurate and it will break with TLS 1.3, which removes the timestamp.)
|
||||
|
||||
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 federation run different NTP daemons, so that a problem with one daemon won't affect all nodes. Some options are:
|
||||
|
||||
* The reference NTP daemon from ntp.org; see [their support website](http://support.ntp.org/bin/view/Support/WebHome)
|
||||
* [OpenNTPD](http://www.openntpd.org/)
|
||||
* [chrony](https://chrony.tuxfamily.org/index.html)
|
||||
* Maybe [NTPsec](https://www.ntpsec.org/), once it's production-ready
|
||||
* Maybe [Ntimed](http://nwtime.org/projects/ntimed/), once it's production-ready
|
||||
* [More](https://en.wikipedia.org/wiki/Ntpd#Implementations)
|
||||
|
||||
It's tricky to make an NTP daemon setup secure. Always install the latest version and read the documentation about how to configure and run it securely.
|
||||
|
||||
The appendix has [some notes on NTP daemon setup](../appendices/ntp-notes.html).
|
||||
|
||||
|
||||
## Set Up the File System for RethinkDB
|
||||
|
||||
If you're just setting up a stand-alone node, then you can probably skip this step.
|
||||
|
||||
Ideally, use a file system that supports direct I/O (Input/Output), a feature whereby file reads and writes go directly from RethinkDB to the storage device, bypassing the operating system read and write caches.
|
||||
|
||||
TODO: What file systems support direct I/O? How can you check? How do you enable it, if necessary?
|
||||
|
||||
See `def install_rethinkdb()` in `deploy-cluster-aws/fabfile.py` for an example of configuring a file system on an AWS instance running Ubuntu.
|
||||
|
||||
Mount the partition for RethinkDB on `/data`: we will tell RethinkDB to store its data there.
|
||||
|
||||
TODO: This section needs more elaboration
|
||||
|
||||
|
||||
## Install RethinkDB Server
|
||||
|
||||
If you don't already have RethinkDB Server installed, you must install it. The RethinkDB documentation has instructions for [how to install RethinkDB Server on a variety of operating systems](http://rethinkdb.com/docs/install/).
|
||||
|
||||
|
||||
## Configure RethinkDB Server
|
||||
|
||||
### Stand-Alone Node
|
||||
|
||||
If you're setting up a stand-alone node (i.e. not intending for it to join a cluster), then the default RethinkDB configuration will work.
|
||||
|
||||
### Cluster Node
|
||||
|
||||
Create a RethinkDB configuration file (text file) named `instance1.conf` with the following contents (explained below):
|
||||
```text
|
||||
directory=/data
|
||||
bind=all
|
||||
direct-io
|
||||
# Replace node?_hostname with actual node hostnames below, e.g. rdb.examples.com
|
||||
join=node0_hostname:29015
|
||||
join=node1_hostname:29015
|
||||
join=node2_hostname:29015
|
||||
# continue until there's a join= line for each node in the federation
|
||||
```
|
||||
|
||||
* `directory=/data` tells the RethinkDB node to store its share of the database data in `/data`.
|
||||
* `bind=all` binds RethinkDB to all local network interfaces (e.g. loopback, Ethernet, wireless, whatever is available), so it can communicate with the outside world. (The default is to bind only to local interfaces.)
|
||||
* `direct-io` tells RethinkDB to use direct I/O (explained earlier).
|
||||
* `join=hostname:29015` lines: A cluster node needs to find out the hostnames of all the other nodes somehow. You _could_ designate one node to be the one that every other node asks, and put that node's hostname in the config file, but that wouldn't be very decentralized. Instead, we include _every_ node in the list of nodes-to-ask.
|
||||
|
||||
If you're curious about the RethinkDB config file, there's [a RethinkDB documentation page about it](https://www.rethinkdb.com/docs/config-file/). The [explanations of the RethinkDB command-line options](https://rethinkdb.com/docs/cli-options/) are another useful reference.
|
||||
|
||||
TODO: Explain how to configure the RethinkDB cluster to be more secure.
|
||||
|
||||
|
||||
## Install Python 3.4+
|
||||
|
||||
If you don't already have it, then you should [install Python 3.4+](https://www.python.org/downloads/).
|
||||
|
||||
If you're testing or developing BigchainDB on a stand-alone node, then you should probably create a Python 3.4+ virtual environment and activate it (e.g. using virtualenv or conda). Later we will install several Python packages and you probably only want those installed in the virtual environment.
|
||||
|
||||
|
||||
## Install BigchainDB Server
|
||||
|
||||
BigchainDB Server has some OS-level dependencies that must be installed.
|
||||
|
||||
On Ubuntu 14.04, we found that the following was enough:
|
||||
```text
|
||||
sudo apt-get update
|
||||
sudo apt-get install g++ python3-dev
|
||||
```
|
||||
|
||||
On Fedora 23, we found that the following was enough (tested in February 2015):
|
||||
```text
|
||||
sudo dnf update
|
||||
sudo dnf install gcc-c++ redhat-rpm-config python3-devel
|
||||
```
|
||||
|
||||
(If you're using a version of Fedora before version 22, you may have to use `yum` instead of `dnf`.)
|
||||
|
||||
With OS-level dependencies installed, you can install BigchainDB Server with `pip` or from source.
|
||||
|
||||
|
||||
### How to Install BigchainDB with pip
|
||||
|
||||
BigchainDB (i.e. both the Server and the officially-supported drivers) is distributed as a Python package on PyPI so you can install it using `pip`. First, make sure you have a version of `pip` installed for Python 3.4+:
|
||||
```text
|
||||
pip -V
|
||||
```
|
||||
|
||||
If it says that `pip` isn't installed, or it says `pip` is associated with a Python version less than 3.4, then you must install a `pip` version associated with Python 3.4+. See [the `pip` installation instructions](https://pip.pypa.io/en/stable/installing/). On Ubuntu 14.04, we found that this works:
|
||||
```text
|
||||
sudo apt-get install python3-setuptools
|
||||
sudo easy_install3 pip
|
||||
pip3 install --upgrade pip wheel setuptools
|
||||
```
|
||||
|
||||
(Note: Using `sudo apt-get python3-pip` also installs a Python 3 version of `pip` (named `pip3`) but we found it installed a very old version and there were issues with updating it.)
|
||||
|
||||
Once you have a version of `pip` associated with Python 3.4+, then you can install BigchainDB Server (and officially-supported BigchainDB drivers) using:
|
||||
```text
|
||||
sudo pip install bigchaindb
|
||||
```
|
||||
(or maybe `sudo pip3 install bigchaindb` or `sudo pip3.4 install bigchaindb`. The `sudo` may not be necessary.)
|
||||
|
||||
Note: You can use `pip` to upgrade the `bigchaindb` package to the latest version using `sudo pip install --upgrade bigchaindb`
|
||||
|
||||
### How to Install BigchainDB from Source
|
||||
|
||||
If you want to install BitchainDB from source because you want to contribute code (i.e. as a BigchainDB developer), then please see the instructions in [the `CONTRIBUTING.md` file](https://github.com/bigchaindb/bigchaindb/blob/master/CONTRIBUTING.md).
|
||||
|
||||
Otherwise, clone the public repository:
|
||||
```text
|
||||
git clone git@github.com:bigchaindb/bigchaindb.git
|
||||
```
|
||||
|
||||
and then install from source:
|
||||
```text
|
||||
python setup.py install
|
||||
```
|
||||
|
||||
|
||||
## Configure BigchainDB Server
|
||||
|
||||
Start by creating a default BigchainDB configuration file (named `.bigchaindb`) in your `$HOME` directory using:
|
||||
```text
|
||||
bigchaindb -y configure
|
||||
```
|
||||
|
||||
There's documentation for the `bigchaindb` command is in the section on [the BigchainDB Command Line Interface (CLI)](bigchaindb-cli.html).
|
||||
|
||||
### Stand-Alone Node
|
||||
|
||||
The default BigchainDB configuration file will work.
|
||||
|
||||
### Cluster Node
|
||||
|
||||
Open `$HOME/.bigchaindb` in your text editor and:
|
||||
|
||||
* 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 `"api_endpoint": "http://localhost:9984/api/v1"` to `"api_endpoint": "http://your_api_hostname:9984/api/v1"`
|
||||
* 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 federation. The keyring should _not_ include your node's public key.
|
||||
|
||||
For more information about the BigchainDB config file, see [Configuring a BigchainDB Node](configuration.html).
|
||||
|
||||
|
||||
## Run RethinkDB Server
|
||||
|
||||
If you didn't create a RethinkDB config file (e.g. because you're running a stand-alone node), then you can start RethinkDB using:
|
||||
```text
|
||||
rethinkdb
|
||||
```
|
||||
|
||||
If you _did_ create a RethinkDB config file, then you should start RethinkDB using:
|
||||
```text
|
||||
rethinkdb --config-file path/to/instance1.conf
|
||||
```
|
||||
|
||||
except replace the path with the actual path to `instance1.conf`.
|
||||
|
||||
Note: It's possible to [make RethinkDB start at system startup](https://www.rethinkdb.com/docs/start-on-startup/).
|
||||
|
||||
You can verify that RethinkDB is running by opening the RethinkDB web interface in your web browser. It should be at `http://rethinkdb-hostname:8080/`. If you're running RethinkDB on localhost, that would be [http://localhost:8080/](http://localhost:8080/).
|
||||
|
||||
|
||||
## Run BigchainDB Server
|
||||
|
||||
### Stand-Alone Node
|
||||
|
||||
It should be enough to do:
|
||||
```text
|
||||
bigchaindb start
|
||||
```
|
||||
|
||||
### Cluster Node
|
||||
|
||||
After all the cluster nodes have started RethinkDB, but before they start BigchainDB, a designated cluster node has to do some RethinkDB cluster configuration by running the following two commands:
|
||||
```text
|
||||
bigchaindb init
|
||||
bigchaindb set-shards numshards
|
||||
```
|
||||
|
||||
where `numshards` should be set equal to the number of nodes expected to be in the cluster (i.e. once all currently-expected nodes have joined).
|
||||
|
||||
(The `bigchain init` command creates the database within RethinkDB, the tables, the indexes, and the genesis block.)
|
||||
|
||||
Once the designated node has run the above two commands, every node can start BigchainDB using:
|
||||
```text
|
||||
bigchaindb start
|
||||
```
|
||||
@ -1,231 +0,0 @@
|
||||
# Installing and Running BigchainDB Server
|
||||
|
||||
We're developing BigchainDB Server on Ubuntu 14.04, but it should work on any OS that runs RethinkDB Server and Python 3.4+. (BigchainDB Server is built on top of RethinkDB Server.)
|
||||
|
||||
BigchainDB Server is intended to be run on each server in a large distributed cluster of servers; it's not very useful running by itself on a single computer. That's _why_ we're developing it on Ubuntu 14.04: it's one of the more common server operating systems.
|
||||
|
||||
Mac OS X users may get the best results [running BigchainDB Server with Docker](installing-server.html#run-bigchaindb-with-docker).
|
||||
|
||||
Windows users may get the best results [running BigchainDB Server in a VM with Vagrant](installing-server.html#how-to-install-bigchaindb-on-a-vm-with-vagrant).
|
||||
|
||||
(BigchainDB clients should run on a much larger array of operating systems.)
|
||||
|
||||
|
||||
## Install and Run RethinkDB Server
|
||||
|
||||
If you don't already have RethinkDB Server installed on your server, you must install it. The RethinkDB documentation has instructions for [how to install RethinkDB Server on a variety of operating systems](http://rethinkdb.com/docs/install/).
|
||||
|
||||
RethinkDB Server doesn't require any special configuration. You can run it by opening a Terminal and entering:
|
||||
```text
|
||||
$ rethinkdb
|
||||
```
|
||||
|
||||
## Install Python 3.4+
|
||||
|
||||
If you don't already have it, then you should [install Python 3.4+](https://www.python.org/downloads/) (maybe in a virtual environment, so it doesn't conflict with other Python projects you're working on).
|
||||
|
||||
## Install BigchainDB Server
|
||||
|
||||
BigchainDB Server has some OS-level dependencies.
|
||||
|
||||
On Ubuntu 14.04, we found that the following was enough:
|
||||
```text
|
||||
$ sudo apt-get update
|
||||
$ sudo apt-get install g++ python3-dev
|
||||
```
|
||||
|
||||
On Fedora 23, we found that the following was enough (tested in February 2015):
|
||||
```text
|
||||
$ sudo dnf update
|
||||
$ sudo dnf install gcc-c++ redhat-rpm-config python3-devel
|
||||
```
|
||||
|
||||
(If you're using a version of Fedora before version 22, you may have to use `yum` instead of `dnf`.)
|
||||
|
||||
With OS-level dependencies installed, you can install BigchainDB Server with `pip` or from source.
|
||||
|
||||
### How to Install BigchainDB with pip
|
||||
|
||||
BigchainDB (i.e. both the Server and the officially-supported drivers) is distributed as a Python package on PyPI so you can install it using `pip`. First, make sure you have a version of `pip` installed for Python 3.4+:
|
||||
```text
|
||||
$ pip -V
|
||||
```
|
||||
|
||||
If it says that `pip` isn't installed, or it says `pip` is associated with a Python version less than 3.4, then you must install a `pip` version associated with Python 3.4+. See [the `pip` installation instructions](https://pip.pypa.io/en/stable/installing/). On Ubuntu 14.04, we found that this works:
|
||||
```text
|
||||
$ sudo apt-get install python3-setuptools
|
||||
$ sudo easy_install3 pip
|
||||
$ pip3 install --upgrade pip wheel setuptools
|
||||
```
|
||||
|
||||
(Note: Using `sudo apt-get python3-pip` also installs a Python 3 version of `pip` (named `pip3`) but we found it installed a very old version and there were issues with updating it.)
|
||||
|
||||
Once you have a version of `pip` associated with Python 3.4+, then you can install BigchainDB Server (and officially-supported BigchainDB drivers) using:
|
||||
```text
|
||||
sudo pip install bigchaindb
|
||||
```
|
||||
(or maybe `sudo pip3 install bigchaindb` or `sudo pip3.4 install bigchaindb`. The `sudo` may not be necessary.)
|
||||
|
||||
Note: You can use `pip` to upgrade the `bigchaindb` package to the latest version using `sudo pip install --upgrade bigchaindb`
|
||||
|
||||
### How to Install BigchainDB from Source
|
||||
|
||||
If you want to install BitchainDB from source because you want to contribute code (i.e. as a BigchainDB developer), then please see the instructions in [the `CONTRIBUTING.md` file](https://github.com/bigchaindb/bigchaindb/blob/master/CONTRIBUTING.md).
|
||||
|
||||
Otherwise, clone the public repository:
|
||||
```text
|
||||
$ git clone git@github.com:bigchaindb/bigchaindb.git
|
||||
```
|
||||
|
||||
and then install from source:
|
||||
```text
|
||||
$ python setup.py install
|
||||
```
|
||||
|
||||
### How to Install BigchainDB on a VM with Vagrant
|
||||
|
||||
One of our community members ([@Mec-Is](https://github.com/Mec-iS)) wrote [a page about how to install BigchainDB on a VM with Vagrant](https://gist.github.com/Mec-iS/b84758397f1b21f21700).
|
||||
|
||||
|
||||
## Run BigchainDB Server
|
||||
|
||||
Once you've installed BigchainDB Server, you can run it. First make sure you have RethinkDB running:
|
||||
```text
|
||||
$ rethinkdb
|
||||
```
|
||||
|
||||
Then open a different terminal and run:
|
||||
```text
|
||||
$ bigchaindb -y configure
|
||||
```
|
||||
|
||||
That creates a configuration file in `$HOME/.bigchaindb` (documented in [the section on configuration](configuration.html)). More documentation about the `bigchaindb` command is in the section on [the BigchainDB Command Line Interface (CLI)](bigchaindb-cli.html).
|
||||
|
||||
You can start BigchainDB Server using:
|
||||
```text
|
||||
$ bigchaindb start
|
||||
```
|
||||
|
||||
If it's the first time you've run `bigchaindb start`, then it creates the database (a RethinkDB database), the tables, the indexes, and the genesis block. It then starts BigchainDB. If you're run `bigchaindb start` or `bigchaindb init` before (and you haven't dropped the database), then `bigchaindb start` just starts BigchainDB.
|
||||
|
||||
|
||||
## Run BigchainDB with Docker
|
||||
|
||||
**NOT for Production Use**
|
||||
|
||||
For those who like using Docker and wish to experiment with BigchainDB in
|
||||
non-production environments, we currently maintain a Docker image and a
|
||||
`Dockerfile` that can be used to build an image for `bigchaindb`.
|
||||
|
||||
### Pull and Run the Image from Docker Hub
|
||||
|
||||
Assuming you have Docker installed, you would proceed as follows.
|
||||
|
||||
In a terminal shell, pull the latest version of the BigchainDB Docker image using:
|
||||
```text
|
||||
docker pull bigchaindb/bigchaindb
|
||||
```
|
||||
|
||||
then do a one-time configuration step to create the config file; we will use
|
||||
the `-y` option to accept all the default values. The configuration file will
|
||||
be stored in a file on your host machine at `~/bigchaindb_docker/.bigchaindb`:
|
||||
|
||||
```text
|
||||
$ docker run --rm -v "$HOME/bigchaindb_docker:/data" -ti \
|
||||
bigchaindb/bigchaindb -y configure
|
||||
Generating keypair
|
||||
Configuration written to /data/.bigchaindb
|
||||
Ready to go!
|
||||
```
|
||||
|
||||
Let's analyze that command:
|
||||
|
||||
* `docker run` tells Docker to run some image
|
||||
* `--rm` remove the container once we are done
|
||||
* `-v "$HOME/bigchaindb_docker:/data"` map the host directory
|
||||
`$HOME/bigchaindb_docker` to the container directory `/data`;
|
||||
this allows us to have the data persisted on the host machine,
|
||||
you can read more in the [official Docker
|
||||
documentation](https://docs.docker.com/engine/userguide/containers/dockervolumes/#mount-a-host-directory-as-a-data-volume)
|
||||
* `-t` allocate a pseudo-TTY
|
||||
* `-i` keep STDIN open even if not attached
|
||||
* `bigchaindb/bigchaindb the image to use
|
||||
* `-y configure` execute the `configure` sub-command (of the `bigchaindb` command) inside the container, with the `-y` option to automatically use all the default config values
|
||||
|
||||
|
||||
After configuring the system, you can run BigchainDB with the following command:
|
||||
|
||||
```text
|
||||
$ docker run -v "$HOME/bigchaindb_docker:/data" -d \
|
||||
--name bigchaindb \
|
||||
-p "58080:8080" -p "59984:9984" \
|
||||
bigchaindb/bigchaindb start
|
||||
```
|
||||
|
||||
The command is slightly different from the previous one, the differences are:
|
||||
|
||||
* `-d` run the container in the background
|
||||
* `--name bigchaindb` give a nice name to the container so it's easier to
|
||||
refer to it later
|
||||
* `-p "58080:8080"` map the host port `58080` to the container port `8080`
|
||||
(the RethinkDB admin interface)
|
||||
* `-p "59984:9984"` map the host port `59984` to the container port `9984`
|
||||
(the BigchainDB API server)
|
||||
* `start` start the BigchainDB service
|
||||
|
||||
Another way to publish the ports exposed by the container is to use the `-P` (or
|
||||
`--publish-all`) option. This will publish all exposed ports to random ports. You can
|
||||
always run `docker ps` to check the random mapping.
|
||||
|
||||
You can also access the RethinkDB dashboard at
|
||||
[http://localhost:58080/](http://localhost:58080/)
|
||||
|
||||
If that doesn't work, then replace `localhost` with the IP or hostname of the
|
||||
machine running the Docker engine. If you are running docker-machine (e.g. on
|
||||
Mac OS X) this will be the IP of the Docker machine (`docker-machine ip
|
||||
machine_name`).
|
||||
|
||||
#### Load Testing with Docker
|
||||
|
||||
Now that we have BigchainDB running in the Docker container named `bigchaindb`, we can
|
||||
start another BigchainDB container to generate a load test for it.
|
||||
|
||||
First, make sure the container named `bigchaindb` is still running. You can check that using:
|
||||
```text
|
||||
docker ps
|
||||
```
|
||||
|
||||
You should see a container named `bigchaindb` in the list.
|
||||
|
||||
You can load test the BigchainDB running in that container by running the `bigchaindb load` command in a second container:
|
||||
|
||||
```text
|
||||
$ docker run --rm -v "$HOME/bigchaindb_docker:/data" -ti \
|
||||
--link bigchaindb \
|
||||
bigchaindb/bigchaindb load
|
||||
```
|
||||
|
||||
Note the `--link` option to link to the first container (named `bigchaindb`).
|
||||
|
||||
Aside: The `bigchaindb load` command has several options (e.g. `-m`). You can read more about it in [the documentation about the BigchainDB command line interface](bigchaindb-cli.html).
|
||||
|
||||
If you look at the RethinkDB dashboard (in your web browser), you should see the effects of the load test. You can also see some effects in the Docker logs using:
|
||||
```text
|
||||
$ docker logs -f bigchaindb
|
||||
```
|
||||
|
||||
### Building Your Own Image
|
||||
|
||||
Assuming you have Docker installed, you would proceed as follows.
|
||||
|
||||
In a terminal shell:
|
||||
```text
|
||||
$ git clone git@github.com:bigchaindb/bigchaindb.git
|
||||
```
|
||||
|
||||
Build the Docker image:
|
||||
```text
|
||||
$ docker build --tag local-bigchaindb .
|
||||
```
|
||||
|
||||
Now you can use your own image to run BigchainDB containers.
|
||||
13
docs/source/topic-guides/assets.md
Normal file
13
docs/source/topic-guides/assets.md
Normal file
@ -0,0 +1,13 @@
|
||||
# How BigchainDB is Good for Asset Registrations & Transfers
|
||||
|
||||
BigchainDB can store data of any kind (within reason), but it's designed to be particularly good for storing asset registrations and transfers:
|
||||
|
||||
* The fundamental thing that one submits to a BigchainDB federation to be checked and stored (if valid) is a _transaction_, and there are two kinds: creation transactions and transfer transactions.
|
||||
* A creation transaction can be use to register any kind of indivisible asset, along with arbitrary metadata.
|
||||
* An asset can have zero, one, or several owners.
|
||||
* The owners of an asset can specify (crypto-)conditions which must be satisified by anyone wishing transfer the asset to new owners. For example, a condition might be that at least 3 of the 5 current owners must cryptographically sign a transfer transaction.
|
||||
* BigchainDB verifies that the conditions have been satisified as part of checking the validity of transfer transactions. (Moreover, anyone can check that they were satisfied.)
|
||||
* BigchainDB prevents double-spending of an asset.
|
||||
* Validated transactions are strongly tamper-resistant; see [the section about immutability / tamper-resistance](immutable.html).
|
||||
|
||||
You can read more about the details of BigchainDB transactions in [the section on Transaction, Block and Vote Models (data models)](models.html).
|
||||
@ -12,4 +12,6 @@ Topic guides give background and explain concepts at a high level.
|
||||
decentralized
|
||||
diversity
|
||||
immutable
|
||||
assets
|
||||
models
|
||||
node-cluster-fed
|
||||
|
||||
13
docs/source/topic-guides/node-cluster-fed.md
Normal file
13
docs/source/topic-guides/node-cluster-fed.md
Normal file
@ -0,0 +1,13 @@
|
||||
# Nodes, Clusters & Federations
|
||||
|
||||
A **BigchainDB node** is a server or set of closely-linked servers running RethinkDB Server, BigchainDB Server, and other BigchainDB-related software. 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 servers 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 (computers). A cluster might be operated by just one person. 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.
|
||||
Loading…
x
Reference in New Issue
Block a user