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

BigchainDB Configuration Settings

Note: At the time of writing, BigchainDB Server code and BigchainDB Python driver code are mixed together, so the following settings are the settings used by BigchainDB Server and also by clients written using the Python driver code. Soon, the code will be separated into server, driver and shared modules, so that BigchainDB Server and BigchainDB clients will have different configuration settings.

The value of each 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
BIGCHAINDB_KEYPAIR_PRIVATE
BIGCHAINDB_KEYRING
BIGCHAINDB_DATABASE_HOST
BIGCHAINDB_DATABASE_PORT
BIGCHAINDB_DATABASE_NAME
BIGCHAINDB_SERVER_BIND
BIGCHAINDB_SERVER_WORKERS
BIGCHAINDB_SERVER_THREADS
BIGCHAINDB_API_ENDPOINT
BIGCHAINDB_STATSD_HOST
BIGCHAINDB_STATSD_PORT
BIGCHAINDB_STATSD_RATE
BIGCHAINDB_CONFIG_PATH

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. (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 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

export BIGCHAINDB_KEYPAIR_PUBLIC=8wHUvvraRo5yEoJAt66UTZaFq9YZ9tFFwcauKPDtjkGw
export BIGCHAINDB_KEYPAIR_PRIVATE=5C5Cknco7YxBRP9AgB1cbUVTL4FAcooxErLygw1DeG2D

Example config file snippet

"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

export BIGCHAINDB_KEYRING=BnCsre9MPBeQK8QZBFznU2dJJ2GwtvnSMdemCmod2XPB:4cYQHoQrvPiut3Sjs8fVR1BMZZpJjMTC4bsMTt9V71aQ

Note how the keys in the list are separated by colons.

Example config file snippet

"keyring": ["BnCsre9MPBeQK8QZBFznU2dJJ2GwtvnSMdemCmod2XPB", 
            "4cYQHoQrvPiut3Sjs8fVR1BMZZpJjMTC4bsMTt9V71aQ"]

Default value (from a config file)

"keyring": []

database.host, database.port & database.name

The RethinkDB database hostname, port and name.

Example using environment variables

export BIGCHAINDB_DATABASE_HOST=localhost
export BIGCHAINDB_DATABASE_PORT=28015
export BIGCHAINDB_DATABASE_NAME=bigchain

Example config file snippet

"database": {
    "host": "localhost",
    "port": 28015,
    "name": "bigchain"
}

Default values (a snippet from bigchaindb/__init__.py)

'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, which is used to serve the HTTP client-server API.

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. 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. (They call it a proxy.)

server.workers is the number of worker processes for handling requests. If None (the default), the value will be (cpu_count * 2 + 1). server.threads is the number of threads-per-worker 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

export BIGCHAINDB_SERVER_BIND=0.0.0.0:9984
export BIGCHAINDB_SERVER_WORKERS=5
export BIGCHAINDB_SERVER_THREADS=5

Example config file snippet

"server": {
    "bind": "0.0.0.0:9984",
    "workers": 5,
    "threads": 5
}

Default values (from a config file)

"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

export BIGCHAINDB_API_ENDPOINT="http://localhost:9984/api/v1"

Example config file snippet

"api_endpoint": "http://webserver.blocks587.net:9984/api/v1"

Default value (from a config file)

"api_endpoint": "http://localhost:9984/api/v1"

statsd.host, statsd.port & statsd.rate

These settings are used to configure where, and how often, StatsD should send data for cluster monitoring 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

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

"statsd": {"host": "localhost", "port": 8125, "rate": 0.01}