Merge branch 'master' into docs/1170/move-http-api-docs-to-top-level-section

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

@@ -16,7 +16,10 @@ For convenience, here's a list of all the relevant environment variables (docume
 `BIGCHAINDB_DATABASE_PORT`<br>
 `BIGCHAINDB_DATABASE_NAME`<br>
 `BIGCHAINDB_DATABASE_REPLICASET`<br>
+`BIGCHAINDB_DATABASE_CONNECTION_TIMEOUT`<br>
+`BIGCHAINDB_DATABASE_MAX_TRIES`<br>
 `BIGCHAINDB_SERVER_BIND`<br>
+`BIGCHAINDB_SERVER_LOGLEVEL`<br>
 `BIGCHAINDB_SERVER_WORKERS`<br>
 `BIGCHAINDB_SERVER_THREADS`<br>
 `BIGCHAINDB_CONFIG_PATH`<br>
@@ -84,9 +87,18 @@ Note how the keys in the list are separated by colons.
 ```
 
 
-## database.backend, database.host, database.port, database.name & database.replicaset
+## database.*
 
-The database backend to use (`rethinkdb` or `mongodb`) and its hostname, port and name. If the database backend is `mongodb`, then there's a fifth setting: the name of the replica set. If the database backend is `rethinkdb`, you *can* set the name of the replica set, but it won't be used for anything.
+The settings with names of the form `database.*` are for the database backend
+(currently either RethinkDB or MongoDB). They are:
+
+* `database.backend` is either `rethinkdb` or `mongodb`.
+* `database.host` is the hostname (FQDN) of the backend database.
+* `database.port` is self-explanatory.
+* `database.name` is a user-chosen name for the database inside RethinkDB or MongoDB, e.g. `bigchain`.
+* `database.replicaset` is only relevant if using MongoDB; it's the name of the MongoDB replica set, e.g. `bigchain-rs`.
+* `database.connection_timeout` is the maximum number of milliseconds that BigchainDB will wait before giving up on one attempt to connect to the database backend. Note: At the time of writing, this setting was only used by MongoDB; there was an open [issue to make RethinkDB use it as well](https://github.com/bigchaindb/bigchaindb/issues/1337).
+* `database.max_tries` is the maximum number of times that BigchainDB will try to establish a connection with the database backend. If 0, then it will try forever.
 
 **Example using environment variables**
 ```text
@@ -95,6 +107,8 @@ export BIGCHAINDB_DATABASE_HOST=localhost
 export BIGCHAINDB_DATABASE_PORT=27017
 export BIGCHAINDB_DATABASE_NAME=bigchain
 export BIGCHAINDB_DATABASE_REPLICASET=bigchain-rs
+export BIGCHAINDB_DATABASE_CONNECTION_TIMEOUT=5000
+export BIGCHAINDB_DATABASE_MAX_TRIES=3
 ```
 
 **Default values**
@@ -104,8 +118,10 @@ If (no environment variables were set and there's no local config file), or you
 "database": {
     "backend": "rethinkdb",
     "host": "localhost",
+    "port": 28015,
     "name": "bigchain",
-    "port": 28015
+    "connection_timeout": 5000,
+    "max_tries": 3
 }
 ```
 
@@ -114,24 +130,31 @@ If you used `bigchaindb -y configure mongodb` to create a default local config f
 "database": {
     "backend": "mongodb",
     "host": "localhost",
-    "name": "bigchain",
     "port": 27017,
-    "replicaset": "bigchain-rs"
+    "name": "bigchain",
+    "replicaset": "bigchain-rs",
+    "connection_timeout": 5000,
+    "max_tries": 3
 }
 ```
 
 
-## server.bind, server.workers & server.threads
+## server.bind, server.loglevel, 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](../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.loglevel` sets the log level of Gunicorn's Error log outputs. See
+[Gunicorn's documentation](http://docs.gunicorn.org/en/latest/settings.html#loglevel)
+for more information.
+
 `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_LOGLEVEL=debug
 export BIGCHAINDB_SERVER_WORKERS=5
 export BIGCHAINDB_SERVER_THREADS=5
 ```
@@ -140,6 +163,7 @@ export BIGCHAINDB_SERVER_THREADS=5
 ```js
 "server": {
     "bind": "0.0.0.0:9984",
+    "loglevel": "debug",
     "workers": 5,
     "threads": 5
 }
@@ -149,6 +173,7 @@ export BIGCHAINDB_SERVER_THREADS=5
 ```js
 "server": {
     "bind": "localhost:9984",
+    "loglevel": "info",
     "workers": null,
     "threads": null
 }