Merge branch 'add-server-and-cluster-docs' into improve-documentation

docs/Makefile

@@ -94,9 +94,9 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/bigchain.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/bigchaindb.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/bigchain.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/bigchaindb.qhc"
 
 .PHONY: applehelp
 applehelp:
@@ -113,8 +113,8 @@ devhelp:
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/bigchain"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/bigchain"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/bigchaindb"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/bigchaindb"
 	@echo "# devhelp"
 
 .PHONY: epub

docs/README.md

@@ -1,4 +1,4 @@
-Coming soon: Read the nicely-formatted long-form documentation on ReadTheDocs.
+[Documentation on ReadTheDocs](http://bigchaindb.readthedocs.org/)
 
 # The BigchainDB Documentation Strategy
 

docs/make.bat

@@ -127,9 +127,9 @@ if "%1" == "qthelp" (
 	echo.
 	echo.Build finished; now you can run "qcollectiongenerator" with the ^
 .qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\bigchain.qhcp
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\bigchaindb.qhcp
 	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\bigchain.ghc
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\bigchaindb.ghc
 	goto end
 )
 

docs/source/admin.md

@@ -1,7 +1,62 @@
 # Server/Cluster Deployment and Administration
-
 This section covers everything which might concern a BigchainDB server/cluster administrator:
 * deployment
 * security
 * monitoring
 * troubleshooting
+
+
+
+## Deploying a local cluster
+One of the advantages of RethinkDB as the storage backend is the easy installation. Developers like to have everything locally, so let's install a local storage backend cluster from scratch.
+Here is an example to run a cluster assuming rethinkdb is already [installed](installing.html#installing-and-running-rethinkdb-server-on-ubuntu-12-04) in
+your system:
+
+    # preparing two additional nodes
+    # remember, that the user who starts rethinkdb must have write access to the paths
+    mkdir -p /path/to/node2
+    mkdir -p /path/to/node3
+
+    # then start your additional nodes
+    rethinkdb --port-offset 1 --directory /path/to/node2 --join localhost:29015
+    rethinkdb --port-offset 2 --directory /path/to/node3 --join localhost:29015
+
+That's all, folks! Cluster is up and running. Check it out in your browser at http://localhost:8080, which opens the console.
+
+Now you can install BigchainDB and run it against the storage backend!
+
+## Securing the storage backend
+We have turned on the bind=all option for connecting other nodes and making RethinkDB accessible from outside the server. Unfortunately this is insecure. So, we will need to block RethinkDB off from the Internet. But we need to allow access to its services from authorized computers.
+
+For the cluster port, we will use a firewall to enclose our cluster. For the web management console and the driver port, we will use SSH tunnels to access them from outside the server. SSH tunnels redirect requests on a client computer to a remote computer over SSH, giving the client access to all of the services only available on the remote server's localhost name space.
+
+Repeat these steps on all your RethinkDB servers.
+
+First, block all outside connections:
+
+    # the web management console
+    sudo iptables -A INPUT -i eth0 -p tcp --dport 8080 -j DROP
+    sudo iptables -I INPUT -i eth0 -s 127.0.0.1 -p tcp --dport 8080 -j ACCEPT
+
+    # the driver port
+    sudo iptables -A INPUT -i eth0 -p tcp --dport 28015 -j DROP
+    sudo iptables -I INPUT -i eth0 -s 127.0.0.1 -p tcp --dport 28015 -j ACCEPT
+
+    # the communication port
+    sudo iptables -A INPUT -i eth0 -p tcp --dport 29015 -j DROP
+    sudo iptables -I INPUT -i eth0 -s 127.0.0.1 -p tcp --dport 29015 -j ACCEPT
+
+Save the iptables config:
+
+    sudo apt-get update
+    sudo apt-get install iptables-persistent
+
+More about iptables you can find in the [man pages](http://linux.die.net/man/8/iptables).
+
+## Monitoring the storage backend
+Monitoring is pretty simple. You can do this via the [monitoring url](http://localhost:8080). Here you see the complete behaviour of all nodes.
+One annotation: if you play around with  replication the number of transaction will increase. So for the real throughput you should devide the number of transactions by the number of replicas.
+
+## Troubleshooting
+Since every software may have some minor issues we are not responsible for the storage backend.
+If your nodes in a sharded and replicated cluster are not in sync, it may help if you delete the data of the affected node and restart the node. If there are no other problems your node will come back and sync within a couple of minutes. You can verify this by monitoring the cluster via the [monitoring url](http://localhost:8080).

docs/source/conf.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
-# bigchain documentation build configuration file, created by
+# BigchainDB documentation build configuration file, created by
 # sphinx-quickstart on Tue Jan 19 14:42:58 2016.
 #
 # This file is execfile()d with the current directory set to its
@@ -59,9 +59,9 @@ source_suffix = ['.rst', '.md']
 master_doc = 'index'
 
 # General information about the project.
-project = 'Bigchain'
-copyright = '2016, ascribe GmbH'
-author = 'ascribe GmbH'
+project = 'BigchainDB'
+copyright = '2016'
+author = 'BigchainDB Contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -213,7 +213,7 @@ html_static_path = ['_static']
 #html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'bigchaindoc'
+htmlhelp_basename = 'bigchaindbdoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -235,8 +235,8 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'bigchain.tex', 'bigchain Documentation',
-     'ascribe GmbH', 'manual'),
+    (master_doc, 'bigchaindb.tex', 'BigchainDB Documentation',
+     author, 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -265,7 +265,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'bigchain', 'bigchain Documentation',
+    (master_doc, 'bigchaindb', 'BigchainDB Documentation',
      [author], 1)
 ]
 
@@ -279,8 +279,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'bigchain', 'bigchain Documentation',
-     author, 'bigchain', 'One line description of project.',
+    (master_doc, 'bigchaindb', 'BigchainDB Documentation',
+     author, 'bigchaindb', 'A scalable blockchain database.',
      'Miscellaneous'),
 ]
 

setup.py

@@ -0,0 +1,29 @@
+"""
+BigchainDB: A Scalable Blockchain Database
+
+For full docs visit https://bigchaindb.readthedocs.org
+
+"""
+from setuptools import setup
+
+setup(
+    name='BigchainDB',
+    version='0.0.0.dev1',
+    description='BigchainDB: A Scalable Blockchain Database',
+    long_description=__doc__,
+    url='https://github.com/BigchainDB/bigchaindb/',
+    author='BigchainDB Contributors',
+    author_email='dev@bigchaindb.com',
+    license='AGPLv3',
+    zip_safe=False,
+
+    classifiers=[
+        'Development Status :: 3 - Alpha',
+        'License :: OSI Approved :: GNU Affero General Public License v3',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.5',
+    ],
+
+    packages=[],
+)