mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
Update documentation
This commit is contained in:
vrde
parent
32e08b7c63
commit
f90254c3c9
@ -25,95 +25,3 @@ $ bigchaindb-benchmark load -h
|
|||||||
Note that you can always start `bigchaindb` using a different config file using the `-c` option.
|
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`.
|
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
|
|
||||||
```
|
|
||||||
|
|||||||
247
docs/source/configuration.md
Normal file
247
docs/source/configuration.md
Normal file
@ -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 <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:
|
||||||
|
|
||||||
|
```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.
|
||||||
|
|
||||||
Loading…
x
Reference in New Issue
Block a user