diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 57b1d12f..de374bb2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,11 +35,18 @@ Familiarize yourself with how we do coding and documentation in the BigchainDB p * [Scott Chacon's blog post about GitHub Flow](http://scottchacon.com/2011/08/31/github-flow.html) * [semantic versioning](http://semver.org/) -### Step 2 - Fork bigchaindb on GitHub +### Step 2 - Install some Dependencies + +* [Install RethinkDB Server](https://rethinkdb.com/docs/install/) +* Make sure you have Python 3.4+ (maybe in a virtualenv) +* [Install BigchaindB Server's OS-level dependencies](http://bigchaindb.readthedocs.io/en/latest/nodes/setup-run-node.html#install-bigchaindb-server) +* [Make sure you have the latest version of pip](http://bigchaindb.readthedocs.io/en/latest/nodes/setup-run-node.html#how-to-install-bigchaindb-with-pip) + +### Step 3 - Fork bigchaindb on GitHub In your web browser, go to [the BigchainDB repository on GitHub](https://github.com/bigchaindb/bigchaindb) and click the `Fork` button in the top right corner. This creates a new Git repository named `bigchaindb` in _your_ GitHub account. -### Step 3 - Clone Your Fork +### Step 4 - Clone Your Fork (This only has to be done once.) In your local terminal, use Git to clone _your_ `bigchaindb` repository to your local computer. Also add the original GitHub bigchaindb/bigchaindb repository as a remote named `upstream` (a convention): ```text @@ -48,7 +55,7 @@ cd bigchaindb git add upstream git@github.com:bigchaindb/bigchaindb.git ``` -### Step 4 - Fetch and Merge the Latest from `upstream/master` +### Step 5 - Fetch and Merge the Latest from `upstream/master` Switch to the `master` branch locally, fetch all `upstream` branches, and merge the just-fetched `upstream/master` branch with the local `master` branch: ```text @@ -57,7 +64,7 @@ git fetch upstream git merge upstream/master ``` -### Step 5 - Install the Python module and the CLI +### Step 6 - Install the Python module and the CLI In order to use and run the source you just cloned from your fork, you need to install BigchainDB on your computer. The core of BigchainDB is a Python module you can install using the standard [Python packaging tools](http://python-packaging-user-guide.readthedocs.org/en/latest/). @@ -65,8 +72,8 @@ We highly suggest you use `pip` and `virtualenv` to manage your local developmen If you need more information on how to do that, refer to the *Python Packaging User Guide* to [install `pip`](http://python-packaging-user-guide.readthedocs.org/en/latest/installing/#requirements-for-installing-packages) and to [create your first `virtualenv`](http://python-packaging-user-guide.readthedocs.org/en/latest/installing/#creating-virtual-environments). Once you have `pip` installed and (optionally) you are in a virtualenv, go to the root of the repository (i.e. where the `setup.py` file is), and type: -```bash -$ pip install -e .[dev] +```text +pip install -e .[dev] ``` This will install the BigchainDB Python module, the CLI, and all the dependencies useful for contributing to the development of BigchainDB. @@ -77,8 +84,10 @@ How? Let's split the command down into its components: - `.` installs what's in the current directory - `[dev]` adds some [extra requirements](https://pythonhosted.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies) to the installation. (If you are curious, open `setup.py` and look for `dev` in the `extras_require` section.) +Aside: An alternative to `pip install -e .[dev]` is `python setup.py develop`. -### Step 6 - Create a New Branch for Each Bug/Feature + +### Step 7 - Create a New Branch for Each Bug/Feature If your new branch is to **fix a bug** identified in a specific GitHub Issue with number `ISSNO`, then name your new branch `bug/ISSNO/short-description-here`. For example, `bug/67/fix-leap-year-crash`. @@ -89,7 +98,7 @@ Otherwise, please give your new branch a short, descriptive, all-lowercase name. git checkout -b new-branch-name ``` -### Step 7 - Make Edits, git add, git commit +### Step 8 - Make Edits, git add, git commit With your new branch checked out locally, make changes or additions to the code or documentation. Remember to: @@ -116,14 +125,14 @@ If your addition or change is substantial, then please add a line or two to the (When you submit your pull request [following the instructions below], we run all the tests automatically, so we will see if some are failing. If you don't know why some tests are failing, you can still submit your pull request, but be sure to note the failing tests and to ask for help with resolving them.) -### Step 8 - Push Your New Branch to origin +### Step 9 - Push Your New Branch to origin Make sure you've commited all the additions or changes you want to include in your pull request. Then push your new branch to origin (i.e. _your_ remote bigchaindb repository). ```text git push origin new-branch-name ``` -### Step 9 - Create a Pull Request +### Step 10 - Create a Pull Request Go to the GitHub website and to _your_ remote bigchaindb repository (i.e. something like https://github.com/your-user-name/bigchaindb). diff --git a/docs/source/index.rst b/docs/source/index.rst index 6f4e7efd..f54767f5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,6 +1,3 @@ -.. You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - BigchainDB Documentation ======================== diff --git a/docs/source/introduction.md b/docs/source/introduction.md index c78a7358..2d2393c8 100644 --- a/docs/source/introduction.md +++ b/docs/source/introduction.md @@ -5,6 +5,16 @@ 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 federation](clusters-feds/federation-set-up.html) (i.a. an organization with a BigchainDB cluster) +* To set up a stand-alone node so you can help contribute to the development of BigchainDB Server, see [the CONTRIBUTING.md file](https://github.com/bigchaindb/bigchaindb/blob/master/CONTRIBUTING.md) +* [Deploy a cluster on AWS](clusters-feds/deploy-on-aws.html) + +(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. @@ -17,3 +27,4 @@ BigchainDB is currently in version 0.X. ([The Releases page on GitHub](https://g ## 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). + diff --git a/docs/source/nodes/setup-run-node.md b/docs/source/nodes/setup-run-node.md index a467bc48..ce880648 100644 --- a/docs/source/nodes/setup-run-node.md +++ b/docs/source/nodes/setup-run-node.md @@ -1,9 +1,6 @@ -# Set Up and Run a Node +# Set Up and Run a Cluster 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 +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). ## Get a Server @@ -24,8 +21,6 @@ TODO: Notes about firewall setup. What ports should be open, for what kinds of t ## 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: @@ -44,8 +39,6 @@ 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? @@ -64,12 +57,6 @@ If you don't already have RethinkDB Server installed, you must install it. The R ## 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 @@ -146,36 +133,25 @@ Note: You can use `pip` to upgrade the `bigchaindb` package to the latest versio ### 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: +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 -``` - -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: +Start by creating a default BigchainDB config file: ```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). +(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: +Edit the created config file: +* Open `$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 `"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. @@ -185,12 +161,7 @@ For more information about the BigchainDB config file, see [Configuring a Bigcha ## 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: +Start RethinkDB using: ```text rethinkdb --config-file path/to/instance1.conf ``` @@ -204,27 +175,20 @@ You can verify that RethinkDB is running by opening the RethinkDB web interface ## 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, one designated cluster node must configure the RethinkDB database by running the following commands: +After all node operators have started RethinkDB, but before they start BigchainDB, one designated node operator must configure the RethinkDB database by running the following commands: ```text bigchaindb init bigchaindb set-shards numshards bigchaindb set-replicas numreplicas ``` +where: + * `bigchaindb init` creates the database within RethinkDB, the tables, the indexes, and the genesis block. * `numshards` should be set to the number of nodes in the initial cluster. * `numreplicas` should be set to the database replication factor decided by the federation. It must be 3 or more for [RethinkDB failover](https://rethinkdb.com/docs/failover/) to work. -Once the RethinkDB database is configured, every node can start BigchainDB using: +Once the RethinkDB database is configured, every node operator can start BigchainDB using: ```text bigchaindb start ``` diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md index c09b9560..c88609ee 100644 --- a/docs/source/quickstart.md +++ b/docs/source/quickstart.md @@ -1,8 +1,6 @@ # Quickstart -This page has instructions to set up a single stand-alone BigchainDB node for learning or experimenting. If you want to set up a BigchainDB node for production, development, benchmarking, or something else, see the [BigchainDB Nodes](nodes/index.html) section. - -We will assume you're using Ubuntu 14.04 or similar. If you're not using Linux, then you might try [running BigchainDB with Docker](nodes/run-with-docker.html). +This page has instructions to set up a single stand-alone BigchainDB node for learning or experimenting. Instructions for other cases are [elsewhere](introduction.html). We will assume you're using Ubuntu 14.04 or similar. If you're not using Linux, then you might try [running BigchainDB with Docker](nodes/run-with-docker.html). A. [Install RethinkDB Server](https://rethinkdb.com/docs/install/ubuntu/)