diff --git a/docs/source/bigchaindb-cli.md b/docs/source/bigchaindb-cli.md index ddb04e1c..4186426e 100644 --- a/docs/source/bigchaindb-cli.md +++ b/docs/source/bigchaindb-cli.md @@ -25,95 +25,3 @@ $ bigchaindb-benchmark load -h Note that you can always start `bigchaindb` using a different config file using the `-c` option. For more information check the help with `bigchaindb -h`. - -# 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: - -```json -{ - - "database": { - "host": "localhost", - "port": 28015 - } - -} -``` - -while your local file `local.json` contains: -```json -{ - "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: -```json -{ - "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. - - -# List of env variables - -``` -- 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 -``` diff --git a/docs/source/configuration.md b/docs/source/configuration.md new file mode 100644 index 00000000..6a906b96 --- /dev/null +++ b/docs/source/configuration.md @@ -0,0 +1,247 @@ +# Configuring a BigchainDB Node + +The standard way to configure a BigchainDB node is to run the command `configure`: + +```text +$ 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 + 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: + +```json +{ + + "database": { + "host": "localhost", + "port": 28015 + } + +} +``` + +while your local file `local.json` contains: +```json +{ + "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: +```json +{ + "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. +