bigchaindb/docs/source/configuration.md

Configuring a BigchainDB Node

The standard way to configure a BigchainDB node is to run the command configure:

$ bigchaindb configure

This command will generate a new keypair and will guide you through the configuration of the system. By default keypair and settings will be saved in the $HOME/.bigchaindb file.

Using a different path for the configuration

By default the configuration is stored in $HOME/.bigchaindb, if you want to specify a different path for your configuration you can use the -c parameter. This works for every subcommand under the bigchaindb executable.

For example, if you want to generate a new configuration file under a specific path, you can run:

$ bigchaindb -c local.json configure
$ bigchaindb -c test.json configure

This will create two new files called local.json and test.json in your current working directory.

From now on, you can refer to those configuration files using the -c parameter, for example:

$ bigchaindb -c local.json show-config

Will show the configuration for local.json.

If you want to start BigchainDB with the test.json configuration, you can try:

$ bigchaindb -c test.json start

Using environ variables to configure the node

Sometimes it's more convenient to use environment variables to configure the system, for example when using Docker or Heroku. Another use case is to have a volatile, throw away configuration you need to test something quickly. In those cases you can configure the system using environment variables.

Every configuration key can be mapped to an environment variable. The environment variables available are:

- BIGCHAINDB_DATABASE_HOST
- BIGCHAINDB_DATABASE_PORT
- BIGCHAINDB_DATABASE_NAME
- BIGCHAINDB_KEYPAIR_PUBLIC
- BIGCHAINDB_KEYPAIR_PRIVATE
- BIGCHAINDB_KEYRING
- BIGCHAINDB_STATSD_HOST
- BIGCHAINDB_STATSD_PORT
- BIGCHAINDB_STATSD_RATE
- BIGCHAINDB_API_ENDPOINT
- BIGCHAINDB_CONSENSUS_PLUGIN
- BIGCHAINDB_SERVER_BIND
- BIGCHAINDB_SERVER_WORKERS
- BIGCHAINDB_SERVER_THREADS

As an example, let's assume we don't have any configuration file stored in the default location $HOME/.bigchaindb.

As you can see, show-config displays the default configuration (and a warning):

$ bigchaindb show-config
WARNING:bigchaindb.config_utils:Cannot find config file `/home/vrde/.bigchaindb`.
{
    "api_endpoint": "http://localhost:9984/api/v1",
    "consensus_plugin": "default",
    "database": {
        "host": "localhost",
        "name": "bigchain",
        "port": 28015
    },
    "keypair": {
        "private": null,
        "public": null
    },
    "keyring": [],
    "server": {
        "bind": "0.0.0.0:9984",
        "threads": null,
        "workers": null
    },
    "statsd": {
        "host": "localhost",
        "port": 8125,
        "rate": 0.01
    }
}

If we try to run the node, the command will fail:

$ bigchaindb start
WARNING:bigchaindb.config_utils:Cannot find config file `/home/vrde/.bigchaindb`.
INFO:bigchaindb.db.utils:Create:
INFO:bigchaindb.db.utils: - database `bigchain`
INFO:bigchaindb.db.utils: - tables
INFO:bigchaindb.db.utils: - indexes
INFO:bigchaindb.db.utils: - genesis block
Traceback (most recent call last):
  File "/home/vrde/.local/share/virtualenvs/bigchain/bin/bigchaindb", line 9, in <module>
    load_entry_point('BigchainDB', 'console_scripts', 'bigchaindb')()
  File "/home/vrde/ascribe/repos/bigchaindb/bigchaindb/commands/bigchain.py", line 137, in main
    start(parser, globals())
  File "/home/vrde/ascribe/repos/bigchaindb/bigchaindb/commands/utils.py", line 41, in start
    func(args)
  File "/home/vrde/ascribe/repos/bigchaindb/bigchaindb/commands/bigchain.py", line 101, in run_start
    db.init()
  File "/home/vrde/ascribe/repos/bigchaindb/bigchaindb/db/utils.py", line 62, in init
    b = bigchaindb.Bigchain()
  File "/home/vrde/ascribe/repos/bigchaindb/bigchaindb/core.py", line 58, in __init__
    raise exceptions.KeypairNotFoundException()
bigchaindb.exceptions.KeypairNotFoundException

This is failing as expected: a BigchainDB node needs at least a key pair to work. We can pass the key pair using environment variables:

$ BIGCHAINDB_KEYPAIR_PUBLIC=26y9EuyGP44JXxqcvF8GbCJGqkiqFXddZzxVjLU3rWbHp \
  BIGCHAINDB_KEYPAIR_PRIVATE=9PkLfHbzXnSSNnb1sSBL73C2MydzKLs5fAHoA4Q7otrG \
  bigchaindb start

We can also run show-config to see how the configuration looks like:

$ BIGCHAINDB_KEYPAIR_PUBLIC=26y9EuyGP44JXxqcvF8GbCJGqkiqFXddZzxVjLU3rWbHp \
  BIGCHAINDB_KEYPAIR_PRIVATE=9PkLfHbzXnSSNnb1sSBL73C2MydzKLs5fAHoA4Q7otrG \
  bigchaindb show-config

WARNING:bigchaindb.config_utils:Cannot find config file `/home/vrde/.bigchaindb`.
{
    "api_endpoint": "http://localhost:9984/api/v1",
    "consensus_plugin": "default",
    "database": {
        "host": "localhost",
        "name": "bigchain",
        "port": 28015
    },
    "keypair": {
        "private": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "public": "26y9EuyGP44JXxqcvF8GbCJGqkiqFXddZzxVjLU3rWbHp"
    },
    "keyring": [],
    "server": {
        "bind": "0.0.0.0:9984",
        "threads": null,
        "workers": null
    },
    "statsd": {
        "host": "localhost",
        "port": 8125,
        "rate": 0.01
    }
}

Precedence in reading configuration values

Note that there is a precedence in reading configuration values:

• local config file;
• environment vars;
• default config file (contained in bigchaindb.__init__).

This means that if the default configuration contains an entry that is:

{

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

}

while your local file local.json contains:

{
    "database": {
        "host": "ec2-xx-xx-xxx-xxx.eu-central-1.compute.amazonaws.com"
    }
}

and you run this command:

$ BIGCHAINDB_DATABASE_HOST=anotherhost.com \
  BIGCHAINDB_DATABASE_PORT=4242 \
  BIGCHAINDB_KEYRING=pubkey0:pubkey1 \
  bigchaindb -c local.json show-config

you will get:

{
    "api_endpoint": "http://localhost:8008/api/v1",
    "consensus_plugin": "default",
    "database": {
        "host": "ec2-xx-xx-xxx-xxx.eu-central-1.compute.amazonaws.com",
        "name": "bigchain",
        "port": 4242
    },
    "keypair": {
        "private": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "public": "nJq6EmdUkvFjQRB5hFvDmvZtv1deb3W3RgmiAq6dyygC"
    },
    "keyring": [
        "pubkey0",
        "pubkey1"
    ],
    "server": {
        "bind": "0.0.0.0:9984",
        "threads": null,
        "workers": null
    },
    "statsd": {
        "host": "localhost",
        "port": 8125,
        "rate": 0.01
    }
}

Note that the type of keyring is a list. If you want to pass a list as an environ variable you need to use colon (:) as separator.