Moved docs directory to docs/server, except README.md

docs/server/source/server-reference/bigchaindb-cli.md

@@ -0,0 +1,85 @@
+# Command Line Interface (CLI)
+
+The command-line command to interact with BigchainDB Server is `bigchaindb`.
+
+
+## bigchaindb \-\-help
+
+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.
+
+If you use the `-c` command-line option, it will generate the file at the specified path:
+```text
+bigchaindb -c path/to/new_config.json configure
+```
+
+If you don't use the `-c` command-line option, the file will be written to `$HOME/.bigchaindb` (the default location where BigchainDB looks for a config file, if one isn't specified).
+
+If you use the `-y` command-line option, then there won't be any interactive prompts: it will just generate a keypair and use the default values for all the other configuration settings.
+```text
+bigchaindb -y configure
+```
+
+
+## bigchaindb show-config
+
+Show the values of the [BigchainDB node configuration settings](configuration.html).
+
+
+## bigchaindb export-my-pubkey
+
+Write the node's public key (i.e. one of its configuration values) to standard output (stdout).
+
+
+## bigchaindb init
+
+Create a RethinkDB database, all RethinkDB database tables, various RethinkDB database indexes, and the genesis block.
+
+Note: The `bigchaindb start` command (see below) always starts by trying a `bigchaindb init` first. If it sees that the RethinkDB database already exists, then it doesn't re-initialize the database. One doesn't have to do `bigchaindb init` before `bigchaindb start`. `bigchaindb init` is useful if you only want to initialize (but not start).
+
+
+## bigchaindb drop
+
+Drop (erase) the RethinkDB database. You will be prompted to make sure. If you want to force-drop the database (i.e. skipping the yes/no prompt), then use `bigchaindb -y drop`
+
+
+## bigchaindb start
+
+Start BigchainDB. It always begins by trying a `bigchaindb init` first. See the note in the documentation for `bigchaindb init`.
+You can also use the `--dev-start-rethinkdb` command line option to automatically start rethinkdb with bigchaindb if rethinkdb is not already running,
+e.g. `bigchaindb --dev-start-rethinkdb start`. Note that this will also shutdown rethinkdb when the bigchaindb process stops.
+The option `--dev-allow-temp-keypair` will generate a keypair on the fly if no keypair is found, this is useful when you want to run a temporary instance of BigchainDB in a Docker container, for example.
+
+
+## bigchaindb load
+
+Write transactions to the backlog (for benchmarking tests). You can learn more about it using:
+```text
+$ bigchaindb load -h
+```
+
+Note: This command uses the Python Server API to write transactions to the database. It _doesn't_ use the HTTP API or a driver that wraps the HTTP API.
+
+
+## bigchaindb set-shards
+
+Set the number of shards in the underlying datastore. For example, the following command will set the number of shards to four:
+```text
+$ bigchaindb set-shards 4
+```
+
+## bigchaindb set-replicas
+
+Set the number of replicas (of each shard) in the underlying datastore. For example, the following command will set the number of replicas to three (i.e. it will set the replication factor to three):
+```text
+$ bigchaindb set-replicas 3
+```

docs/server/source/server-reference/configuration.md

@@ -0,0 +1,177 @@
+# Configuration Settings
+
+The value of each BigchainDB Server configuration setting is determined according to the following rules:
+
+* If it's set by an environment variable, then use that value
+* Otherwise, if it's set in a local config file, then use that value
+* Otherwise, use the default value
+
+For convenience, here's a list of all the relevant environment variables (documented below):
+
+`BIGCHAINDB_KEYPAIR_PUBLIC`<br>
+`BIGCHAINDB_KEYPAIR_PRIVATE`<br>
+`BIGCHAINDB_KEYRING`<br>
+`BIGCHAINDB_DATABASE_HOST`<br>
+`BIGCHAINDB_DATABASE_PORT`<br>
+`BIGCHAINDB_DATABASE_NAME`<br>
+`BIGCHAINDB_SERVER_BIND`<br>
+`BIGCHAINDB_SERVER_WORKERS`<br>
+`BIGCHAINDB_SERVER_THREADS`<br>
+`BIGCHAINDB_API_ENDPOINT`<br>
+`BIGCHAINDB_STATSD_HOST`<br>
+`BIGCHAINDB_STATSD_PORT`<br>
+`BIGCHAINDB_STATSD_RATE`<br>
+`BIGCHAINDB_CONFIG_PATH`<br>
+
+The local config file is `$HOME/.bigchaindb` by default (a file which might not even exist), but you can tell BigchainDB to use a different file by using the `-c` command-line option, e.g. `bigchaindb -c path/to/config_file.json start`
+or using the `BIGCHAINDB_CONFIG_PATH` environment variable, e.g. `BIGHAINDB_CONFIG_PATH=.my_bigchaindb_config bigchaindb start`.
+Note that the `-c` command line option will always take precedence if both the `BIGCHAINDB_CONFIG_PATH` and the `-c` command line option are used.
+
+You can read the current default values in the file [bigchaindb/\_\_init\_\_.py](https://github.com/bigchaindb/bigchaindb/blob/master/bigchaindb/__init__.py). (The link is to the latest version.)
+
+Running `bigchaindb -y configure` will generate a local config file in `$HOME/.bigchaindb` with all the default values, with two exceptions: It will generate a valid private/public keypair, rather than using the default keypair (`None` and `None`).
+
+
+## keypair.public & keypair.private
+
+The [cryptographic keypair](../appendices/cryptography.html) used by the node. The public key is how the node idenifies itself to the world. The private key is used to generate cryptographic signatures. Anyone with the public key can verify that the signature was generated by whoever had the corresponding private key.
+
+**Example using environment variables**
+```text
+export BIGCHAINDB_KEYPAIR_PUBLIC=8wHUvvraRo5yEoJAt66UTZaFq9YZ9tFFwcauKPDtjkGw
+export BIGCHAINDB_KEYPAIR_PRIVATE=5C5Cknco7YxBRP9AgB1cbUVTL4FAcooxErLygw1DeG2D
+```
+
+**Example config file snippet**
+```js
+"keypair": {
+  "public": "8wHUvvraRo5yEoJAt66UTZaFq9YZ9tFFwcauKPDtjkGw",
+  "private": "5C5Cknco7YxBRP9AgB1cbUVTL4FAcooxErLygw1DeG2D"
+}
+```
+
+Internally (i.e. in the Python code), both keys have a default value of `None`, but that's not a valid key. Therefore you can't rely on the defaults for the keypair. If you want to run BigchainDB, you must provide a valid keypair, either in the environment variables or in the local config file. You can generate a local config file with a valid keypair (and default everything else) using `bigchaindb -y configure`.
+
+
+## keyring
+
+A list of the public keys of all the nodes in the cluster, excluding the public key of this node. 
+
+**Example using an environment variable**
+```text
+export BIGCHAINDB_KEYRING=BnCsre9MPBeQK8QZBFznU2dJJ2GwtvnSMdemCmod2XPB:4cYQHoQrvPiut3Sjs8fVR1BMZZpJjMTC4bsMTt9V71aQ
+```
+
+Note how the keys in the list are separated by colons.
+
+**Example config file snippet**
+```js
+"keyring": ["BnCsre9MPBeQK8QZBFznU2dJJ2GwtvnSMdemCmod2XPB", 
+            "4cYQHoQrvPiut3Sjs8fVR1BMZZpJjMTC4bsMTt9V71aQ"]
+```
+
+**Default value (from a config file)**
+```js
+"keyring": []
+```
+
+
+## database.host, database.port & database.name
+
+The RethinkDB database hostname, port and name.
+
+**Example using environment variables**
+```text
+export BIGCHAINDB_DATABASE_HOST=localhost
+export BIGCHAINDB_DATABASE_PORT=28015
+export BIGCHAINDB_DATABASE_NAME=bigchain
+```
+
+**Example config file snippet**
+```js
+"database": {
+    "host": "localhost",
+    "port": 28015,
+    "name": "bigchain"
+}
+```
+
+**Default values (a snippet from `bigchaindb/__init__.py`)**
+```python
+'database': {
+    'host': os.environ.get('BIGCHAINDB_DATABASE_HOST', 'localhost'),
+    'port': 28015,
+    'name': 'bigchain',
+}
+```
+
+
+## server.bind, server.workers & server.threads
+
+These settings are for the [Gunicorn HTTP server](http://gunicorn.org/), which is used to serve the [HTTP client-server API](../drivers-clients/http-client-server-api.html).
+
+`server.bind` is where to bind the Gunicorn HTTP server socket. It's a string. It can be any valid value for [Gunicorn's bind setting](http://docs.gunicorn.org/en/stable/settings.html#bind). If you want to allow IPv4 connections from anyone, on port 9984, use '0.0.0.0:9984'. In a production setting, we recommend you use Gunicorn behind a reverse proxy server. If Gunicorn and the reverse proxy are running on the same machine, then use 'localhost:PORT' where PORT is _not_ 9984 (because the reverse proxy needs to listen on port 9984). Maybe use PORT=9983 in that case because we know 9983 isn't used. If Gunicorn and the reverse proxy are running on different machines, then use 'A.B.C.D:9984' where A.B.C.D is the IP address of the reverse proxy. There's [more information about deploying behind a reverse proxy in the Gunicorn documentation](http://docs.gunicorn.org/en/stable/deploy.html). (They call it a proxy.)
+
+`server.workers` is [the number of worker processes](http://docs.gunicorn.org/en/stable/settings.html#workers) for handling requests. If `None` (the default), the value will be (cpu_count * 2 + 1). `server.threads` is [the number of threads-per-worker](http://docs.gunicorn.org/en/stable/settings.html#threads) for handling requests. If `None` (the default), the value will be (cpu_count * 2 + 1). The HTTP server will be able to handle `server.workers` * `server.threads` requests simultaneously.
+
+**Example using environment variables**
+```text
+export BIGCHAINDB_SERVER_BIND=0.0.0.0:9984
+export BIGCHAINDB_SERVER_WORKERS=5
+export BIGCHAINDB_SERVER_THREADS=5
+```
+
+**Example config file snippet**
+```js
+"server": {
+    "bind": "0.0.0.0:9984",
+    "workers": 5,
+    "threads": 5
+}
+```
+
+**Default values (from a config file)**
+```js
+"server": {
+    "bind": "localhost:9984",
+    "workers": null,
+    "threads": null
+}
+```
+
+
+## api_endpoint
+
+`api_endpoint` is the URL where a BigchainDB client can get access to the HTTP client-server API.
+
+**Example using an environment variable**
+```text
+export BIGCHAINDB_API_ENDPOINT="http://localhost:9984/api/v1"
+```
+
+**Example config file snippet**
+```js
+"api_endpoint": "http://webserver.blocks587.net:9984/api/v1"
+```
+
+**Default value (from a config file)**
+```js
+"api_endpoint": "http://localhost:9984/api/v1"
+```
+
+
+## statsd.host, statsd.port & statsd.rate
+
+These settings are used to configure where, and how often, [StatsD](https://github.com/etsy/statsd) should send data for [cluster monitoring](../clusters-feds/monitoring.html) purposes. `statsd.host` is the hostname of the monitoring server, where StatsD should send its data. `stats.port` is the port. `statsd.rate` is the fraction of transaction operations that should be sampled. It's a float between 0.0 and 1.0.
+
+**Example using environment variables**
+```text
+export BIGCHAINDB_STATSD_HOST="http://monitor.monitors-r-us.io"
+export BIGCHAINDB_STATSD_PORT=8125
+export BIGCHAINDB_STATSD_RATE=0.01
+```
+
+**Example config file snippet: the default**
+```js
+"statsd": {"host": "localhost", "port": 8125, "rate": 0.01}
+```

docs/server/source/server-reference/index.rst

@@ -0,0 +1,8 @@
+Settings & CLI
+==============
+
+.. toctree::
+   :maxdepth: 1
+
+   configuration
+   bigchaindb-cli