mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
Merge branch 'master' into update-server-docs-re-cc
This commit is contained in:
Troy McConaghy
@@ -21,4 +21,4 @@ We’re actively exploring ways that BigchainDB can be used with other blockchai
|
||||
|
||||
.. note::
|
||||
|
||||
We used the word "owners" somewhat loosely above. A more accurate word might be fulfillers, signers, controllers, or tranfer-enablers. See BigchainDB Server `issue #626 <https://github.com/bigchaindb/bigchaindb/issues/626>`_.
|
||||
We used the word "owners" somewhat loosely above. A more accurate word might be fulfillers, signers, controllers, or transfer-enablers. See BigchainDB Server `issue #626 <https://github.com/bigchaindb/bigchaindb/issues/626>`_.
|
||||
|
||||
@@ -7,16 +7,13 @@ BigchainDB will run the subset of smart contracts expressible using "crypto-cond
|
||||
|
||||
The owners of an asset can impose conditions on it that must be met for the asset to be transferred to new owners. Examples of possible conditions (crypto-conditions) include:
|
||||
|
||||
- The current owner must sign the transfer transaction (one which transfers ownership to new owners)
|
||||
- Three out of five current owners must sign the transfer transaction
|
||||
- (Shannon and Kelly) or Morgan must sign the transfer transaction
|
||||
- Anyone who provides the secret password (technically, the preimage of a known hash) can create a valid transfer transaction
|
||||
- The current owner must sign the transfer transaction (one which transfers ownership to new owners).
|
||||
- Three out of five current owners must sign the transfer transaction.
|
||||
- (Shannon and Kelly) or Morgan must sign the transfer transaction.
|
||||
|
||||
Crypto-conditions can be quite complex if-this-then-that type conditions, where the "this" can be a long boolean expression. Crypto-conditions can't include loops or recursion and are therefore will always run/check in finite time.
|
||||
|
||||
BigchainDB also supports a timeout condition which enables it to support a form of escrow.
|
||||
|
||||
.. note::
|
||||
|
||||
We used the word "owners" somewhat loosely above. A more accurate word might be fulfillers, signers, controllers, or tranfer-enablers. See BigchainDB Server `issue #626 <https://github.com/bigchaindb/bigchaindb/issues/626>`_.
|
||||
We used the word "owners" somewhat loosely above. A more accurate word might be fulfillers, signers, controllers, or transfer-enablers. See BigchainDB Server `issue #626 <https://github.com/bigchaindb/bigchaindb/issues/626>`_.
|
||||
|
||||
@@ -15,30 +15,57 @@ one might register an identity or a creative work. The things are often called
|
||||
"assets" but they might not be literal assets.
|
||||
|
||||
BigchainDB supports divisible assets as of BigchainDB Server v0.8.0.
|
||||
That means you can create/register an asset with an initial quantity,
|
||||
e.g. 700 oak trees. Divisible assets can be split apart or recombined
|
||||
by transfer transactions (described more below).
|
||||
That means you can create/register an asset with an initial number of "shares."
|
||||
For example, A CREATE transaction could register a truckload of 50 oak trees.
|
||||
Each share of a divisible asset must be interchangeable with each other share;
|
||||
the shares must be fungible.
|
||||
|
||||
A CREATE transaction also establishes, in its outputs, the conditions that must
|
||||
be met to transfer the asset(s). The conditions may also be associated with a
|
||||
list of public keys that, depending on the condition, may have full or partial
|
||||
control over the asset(s). For example, there may be a condition that any
|
||||
transfer must be signed (cryptographically) by the private key associated with a
|
||||
given public key. More sophisticated conditions are possible. BigchainDB's
|
||||
conditions are based on the crypto-conditions of the [Interledger Protocol
|
||||
(ILP)](https://interledger.org/).
|
||||
A CREATE transaction can have one or more outputs.
|
||||
Each output has an associated amount: the number of shares tied to that output.
|
||||
For example, if the asset consists of 50 oak trees,
|
||||
one output might have 35 oak trees for one set of owners,
|
||||
and the other output might have 15 oak trees for another set of owners.
|
||||
|
||||
Each output also has an associated condition: the condition that must be met
|
||||
(by a TRANSFER transaction) to transfer/spend the output.
|
||||
BigchainDB supports a variety of conditions,
|
||||
a subset of the [Interledger Protocol (ILP)](https://interledger.org/)
|
||||
crypto-conditions. For details, see
|
||||
[the documentation about Inputs and Outputs](https://docs.bigchaindb.com/projects/server/en/latest/data-models/inputs-outputs.html).
|
||||
|
||||
Each output also has a list of all the public keys associated
|
||||
with the conditions on that output.
|
||||
Loosely speaking, that list might be interpreted as the list of "owners."
|
||||
A more accurate word might be fulfillers, signers, controllers,
|
||||
or transfer-enablers.
|
||||
See BigchainDB Server [issue #626](https://github.com/bigchaindb/bigchaindb/issues/626).
|
||||
|
||||
A CREATE transaction must be signed by all the owners.
|
||||
(If you're looking for that signature,
|
||||
it's in the one "fulfillment" of the one input, albeit encoded.)
|
||||
|
||||
|
||||
## TRANSFER Transactions
|
||||
|
||||
A TRANSFER transaction can transfer an asset
|
||||
by providing inputs which fulfill the current output conditions on the asset.
|
||||
It must also specify new transfer conditions.
|
||||
A TRANSFER transaction can transfer/spend one or more outputs
|
||||
on other transactions (CREATE transactions or other TRANSFER transactions).
|
||||
Those outputs must all be associated with the same asset;
|
||||
a TRANSFER transaction can only transfer shares of one asset at a time.
|
||||
|
||||
Each input on a TRANSFER transaction connects to one output
|
||||
on another transaction.
|
||||
Each input must satisfy the condition on the output it's trying
|
||||
to transfer/spend.
|
||||
|
||||
A TRANSFER transaction can have one or more outputs,
|
||||
just like a CREATE transaction (described above).
|
||||
The total number of shares coming in on the inputs must equal
|
||||
the total number of shares going out on the outputs.
|
||||
|
||||
**Example 1:** Suppose a red car is owned and controlled by Joe.
|
||||
Suppose the current transfer condition on the car says
|
||||
that any valid transfer must be signed by Joe.
|
||||
Joe and a buyer named Rae could build a TRANSFER transaction containing
|
||||
Joe could build a TRANSFER transaction containing
|
||||
an input with Joe's signature (to fulfill the current output condition)
|
||||
plus a new output condition saying that any valid transfer
|
||||
must be signed by Rae.
|
||||
@@ -62,3 +89,11 @@ When a node is asked to check if a transaction is valid, it checks several
|
||||
things. We documented those things in a post on *The BigchainDB Blog*:
|
||||
["What is a Valid Transaction in BigchainDB?"](https://blog.bigchaindb.com/what-is-a-valid-transaction-in-bigchaindb-9a1a075a9598)
|
||||
(Note: That post was about BigchainDB Server v1.0.0.)
|
||||
|
||||
|
||||
## Example Transactions
|
||||
|
||||
There are example BigchainDB transactions in
|
||||
[the HTTP API documentation](https://docs.bigchaindb.com/projects/server/en/latest/http-client-server-api.html)
|
||||
and
|
||||
[the Python Driver documentation](https://docs.bigchaindb.com/projects/py-driver/en/latest/usage.html).
|
||||
|
||||
@@ -206,11 +206,11 @@ unspent outputs.
|
||||
|
||||
[
|
||||
{
|
||||
"output": 0,
|
||||
"output_index": 0,
|
||||
"transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e"
|
||||
},
|
||||
{
|
||||
"output": 1,
|
||||
"output_index": 1,
|
||||
"transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e"
|
||||
}
|
||||
]
|
||||
@@ -238,7 +238,7 @@ unspent outputs.
|
||||
|
||||
[
|
||||
{
|
||||
"output": 0,
|
||||
"output_index": 0,
|
||||
"transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e"
|
||||
}
|
||||
]
|
||||
@@ -266,7 +266,7 @@ unspent outputs.
|
||||
|
||||
[
|
||||
{
|
||||
"output": 1,
|
||||
"output_index": 1,
|
||||
"transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e"
|
||||
}
|
||||
]
|
||||
|
||||
@@ -173,6 +173,6 @@ set up NGINX in your new node.
|
||||
Step 8: Test Your New BigchainDB Node
|
||||
-------------------------------------
|
||||
|
||||
Please refer to the testing steps :ref:`here <Step 16: Verify the BigchainDB
|
||||
Please refer to the testing steps :ref:`here <Step 17: Verify the BigchainDB
|
||||
Node Setup>` to verify that your new BigchainDB node is working as expected.
|
||||
|
||||
|
||||
@@ -33,15 +33,17 @@ by going to the ``bdb-cluster-ca/easy-rsa-3.0.1/easyrsa3`` directory and using:
|
||||
|
||||
./easyrsa build-ca
|
||||
|
||||
You will be prompted to enter the Distinguished Name for this CA. You can hit
|
||||
enter to accept the default values or change it at each prompt.
|
||||
|
||||
You will also be asked to enter a PEM pass phrase for encrypting the ``ca.key`` file.
|
||||
You will also be asked to enter a PEM pass phrase (for encrypting the ``ca.key`` file).
|
||||
Make sure to securely store that PEM pass phrase.
|
||||
If you lose it, you won't be able to add or remove entities from your PKI infrastructure in the future.
|
||||
|
||||
It will ask several other questions.
|
||||
You can accept all the defaults [in brackets] by pressing Enter.
|
||||
You will be prompted to enter the Distinguished Name (DN) information for this CA.
|
||||
For each field, you can accept the default value [in brackets] by pressing Enter.
|
||||
|
||||
.. warning::
|
||||
|
||||
Don't accept the default value of OU (``IT``). Instead, enter the value ``ROOT-CA``.
|
||||
|
||||
While ``Easy-RSA CA`` *is* a valid and acceptable Common Name,
|
||||
you should probably enter a name based on the name of the managing organization,
|
||||
e.g. ``Omega Ledger CA``.
|
||||
|
||||
@@ -24,7 +24,7 @@ Step 2: Create the Client Private Key and CSR
|
||||
---------------------------------------------
|
||||
|
||||
You can create the client private key and certificate signing request (CSR)
|
||||
by going into the directory ``client-cert/easy-rsa-3.0.1/easyrsa``
|
||||
by going into the directory ``client-cert/easy-rsa-3.0.1/easyrsa3``
|
||||
and using:
|
||||
|
||||
.. code:: bash
|
||||
@@ -33,25 +33,37 @@ and using:
|
||||
|
||||
./easyrsa gen-req bdb-instance-0 nopass
|
||||
|
||||
You should change ``bdb-instance-0`` to a value that reflects what the
|
||||
client certificate is being used for.
|
||||
You should change the Common Name (e.g. ``bdb-instance-0``)
|
||||
to a value that reflects what the
|
||||
client certificate is being used for, e.g. ``mdb-mon-instance-3`` or ``mdb-bak-instance-4``. (The final integer is specific to your BigchainDB node in the BigchainDB cluster.)
|
||||
|
||||
Tip: You can get help with the ``easyrsa`` command (and its subcommands)
|
||||
by using the subcommand ``./easyrsa help``
|
||||
You will be prompted to enter the Distinguished Name (DN) information for this certificate. For each field, you can accept the default value [in brackets] by pressing Enter.
|
||||
|
||||
.. warning::
|
||||
|
||||
Don't accept the default value of OU (``IT``). Instead, enter the value
|
||||
``BigchainDB-Instance``, ``MongoDB-Mon-Instance`` or ``MongoDB-Backup-Instance``
|
||||
as appropriate.
|
||||
|
||||
Aside: The ``nopass`` option means "do not encrypt the private key (default is encrypted)". You can get help with the ``easyrsa`` command (and its subcommands)
|
||||
by using the subcommand ``./easyrsa help``.
|
||||
|
||||
|
||||
Step 3: Get the Client Certificate Signed
|
||||
-----------------------------------------
|
||||
|
||||
The CSR file (created in the previous step)
|
||||
should be located in ``pki/reqs/bdb-instance-0.req``.
|
||||
The CSR file created in the previous step
|
||||
should be located in ``pki/reqs/bdb-instance-0.req``
|
||||
(or whatever Common Name you used in the ``gen-req`` command above).
|
||||
You need to send it to the organization managing the cluster
|
||||
so that they can use their CA
|
||||
to sign the request.
|
||||
(The managing organization should already have a self-signed CA.)
|
||||
|
||||
If you are the admin of the managing organization's self-signed CA,
|
||||
then you can import the CSR and use Easy-RSA to sign it. For example:
|
||||
then you can import the CSR and use Easy-RSA to sign it.
|
||||
Go to your ``bdb-cluster-ca/easy-rsa-3.0.1/easyrsa3/``
|
||||
directory and do something like:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
|
||||
@@ -37,8 +37,14 @@ Configure MongoDB Cloud Manager for Monitoring
|
||||
|
||||
* Enter the port number as ``27017``, with no authentication.
|
||||
|
||||
* If you have authentication enabled, select the option to enable
|
||||
authentication and specify the authentication mechanism as per your
|
||||
deployment. The default BigchainDB production deployment currently
|
||||
supports ``X.509 Client Certificate`` as the authentication mechanism.
|
||||
|
||||
* If you have TLS enabled, select the option to enable TLS/SSL for MongoDB
|
||||
connections, and click ``Continue``.
|
||||
connections, and click ``Continue``. This should already be selected for
|
||||
you in case you selected ``X.509 Client Certificate`` above.
|
||||
|
||||
* Once the deployment is found, click the ``Continue`` button again.
|
||||
This may take about a minute or two.
|
||||
@@ -66,8 +72,17 @@ Configure MongoDB Cloud Manager for Backup
|
||||
* Hover over the ``Status`` column of your backup and click ``Start``
|
||||
to start the backup.
|
||||
|
||||
* Select the replica set on the side pane and check the box to allow TLS/SSL
|
||||
connections.
|
||||
* Select the replica set on the side pane.
|
||||
|
||||
* If you have authentication enabled, select the authentication mechanism as
|
||||
per your deployment. The default BigchainDB production deployment currently
|
||||
supports ``X.509 Client Certificate`` as the authentication mechanism.
|
||||
|
||||
* If you have TLS enabled, select the checkbox ``Replica set allows TLS/SSL
|
||||
connections``. This should be selected by default in case you selected
|
||||
``X.509 Client Certificate`` as the auth mechanism above.
|
||||
|
||||
* Choose the ``WiredTiger`` storage engine.
|
||||
|
||||
* Verify the details of your MongoDB instance and click on ``Start``.
|
||||
|
||||
@@ -75,4 +90,3 @@ Configure MongoDB Cloud Manager for Backup
|
||||
During this process, the UI will show the status of the backup process.
|
||||
|
||||
* Verify that data is being backed up on the UI.
|
||||
|
||||
|
||||
@@ -69,16 +69,22 @@ The comments in the file explain what each of the variables mean.
|
||||
echo 'set_var EASYRSA_REQ_OU "IT"' >> vars
|
||||
echo 'set_var EASYRSA_REQ_EMAIL "dev@bigchaindb.com"' >> vars
|
||||
|
||||
Note: Later, when building a CA or generating a certificate signing request, you will be prompted to enter a value for the OU (or to accept the default). You should change the default OU from ``IT`` to one of the following, as appropriate:
|
||||
``ROOT-CA``,
|
||||
``MongoDB-Instance``, ``BigchainDB-Instance``, ``MongoDB-Mon-Instance`` or
|
||||
``MongoDB-Backup-Instance``.
|
||||
To understand why, see `the MongoDB Manual <https://docs.mongodb.com/manual/tutorial/configure-x509-client-authentication/>`_.
|
||||
There are reminders to do this in the relevant docs.
|
||||
|
||||
|
||||
Step 4: Maybe Edit x509-types/server
|
||||
------------------------------------
|
||||
|
||||
.. warning::
|
||||
|
||||
Only do this step if you are setting up a self-signed CA
|
||||
or creating a server/member certificate.
|
||||
Only do this step if you are setting up a self-signed CA.
|
||||
|
||||
Edit the file ``x509-types/server`` and change
|
||||
``extendedKeyUsage = serverAuth`` to
|
||||
``extendedKeyUsage = serverAuth,clientAuth``.
|
||||
See `the MongoDB documentation about x.509 authentication <https://docs.mongodb.com/manual/core/security-x.509/>`_ to understand why.
|
||||
Edit the file ``x509-types/server`` and change
|
||||
``extendedKeyUsage = serverAuth`` to
|
||||
``extendedKeyUsage = serverAuth,clientAuth``.
|
||||
See `the MongoDB documentation about x.509 authentication <https://docs.mongodb.com/manual/core/security-x.509/>`_ to understand why.
|
||||
|
||||
@@ -29,8 +29,8 @@ where all data values must be base64-encoded.
|
||||
This is true of all Kubernetes ConfigMaps and Secrets.)
|
||||
|
||||
|
||||
vars
|
||||
~~~~
|
||||
vars.mdb-instance-name and Similar
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Your BigchainDB cluster organization should have a standard way
|
||||
of naming instances, so the instances in your BigchainDB node
|
||||
@@ -59,12 +59,14 @@ of all *other* nodes in your BigchainDB cluster
|
||||
* If you're deploying the first node in the cluster,
|
||||
the value should be ``""`` (an empty string).
|
||||
* If you're deploying the second node in the cluster,
|
||||
the value should be one public key inside double quotes.
|
||||
the value should be the BigchainDB public key of the first/original
|
||||
node in the cluster.
|
||||
For example,
|
||||
``"EPQk5i5yYpoUwGVM8VKZRjM8CYxB6j8Lu8i8SG7kGGce"``
|
||||
* If there are two or more other nodes already in the cluster,
|
||||
the value should be a colon-separated list of public keys
|
||||
inside double quotes.
|
||||
the value should be a colon-separated list
|
||||
of the BigchainDB public keys
|
||||
of those other nodes.
|
||||
For example,
|
||||
``"DPjpKbmbPYPKVAuf6VSkqGCf5jzrEh69Ldef6TrLwsEQ:EPQk5i5yYpoUwGVM8VKZRjM8CYxB6j8Lu8i8SG7kGGce"``
|
||||
|
||||
@@ -89,6 +91,63 @@ Note that ``ca.pem`` is just another name for ``ca.crt``
|
||||
(the certificate of your BigchainDB cluster's self-signed CA).
|
||||
|
||||
|
||||
bdb-certs.bdb-user
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is the user name that BigchainDB uses to authenticate itself to the
|
||||
backend MongoDB database.
|
||||
|
||||
We need to specify the user name *as seen in the certificate* issued to
|
||||
the BigchainDB instance in order to authenticate correctly. Use
|
||||
the following ``openssl`` command to extract the user name from the
|
||||
certificate:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ openssl x509 -in <path to the bigchaindb certificate> \
|
||||
-inform PEM -subject -nameopt RFC2253
|
||||
|
||||
You should see an output line that resembles:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
subject= emailAddress=dev@bigchaindb.com,CN=test-bdb-ssl,OU=BigchainDB-Instance,O=BigchainDB GmbH,L=Berlin,ST=Berlin,C=DE
|
||||
|
||||
The ``subject`` line states the complete user name we need to use for this
|
||||
field (``bdb-certs.bdb-user``), i.e.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
emailAddress=dev@bigchaindb.com,CN=test-bdb-ssl,OU=BigchainDB-Instance,O=BigchainDB GmbH,L=Berlin,ST=Berlin,C=DE
|
||||
|
||||
|
||||
threescale-credentials.*
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you're not using 3scale,
|
||||
you can delete the ``threescale-credentials`` Secret
|
||||
or leave all the values blank (``""``).
|
||||
|
||||
If you *are* using 3scale, you can get the value for ``frontend-api-dns-name``
|
||||
using something like ``echo "your.nodesubdomain.net" | base64 -w 0``
|
||||
|
||||
To get the values for ``secret-token``, ``service-id``,
|
||||
``version-header`` and ``provider-key``, login to your 3scale admin,
|
||||
then click **APIs** and click on **Integration** for the relevant API.
|
||||
Scroll to the bottom of the page and click the small link
|
||||
in the lower right corner, labelled **Download the NGINX Config files**.
|
||||
You'll get a ``.zip`` file.
|
||||
Unzip it, then open the ``.conf`` file and the ``.lua`` file.
|
||||
You should be able to find all the values in those files.
|
||||
You have to be careful because it will have values for *all* your APIs,
|
||||
and some values vary from API to API.
|
||||
The ``version-header`` is the timestamp in a line that looks like:
|
||||
|
||||
.. code::
|
||||
|
||||
proxy_set_header X-3scale-Version "2017-06-28T14:57:34Z";
|
||||
|
||||
|
||||
Deploy Your config-map.yaml and secret.yaml
|
||||
-------------------------------------------
|
||||
|
||||
|
||||
@@ -128,7 +128,22 @@ Step 4.1: Vanilla NGINX
|
||||
the ConfigMap followed by ``-dep``. For example, if the value set in the
|
||||
``ngx-instance-name`` is ``ngx-instance-0``, set the
|
||||
``spec.selector.app`` to ``ngx-instance-0-dep``.
|
||||
|
||||
|
||||
* Set ``ngx-public-mdb-port.port`` to 27017, or the port number on which you
|
||||
want to expose MongoDB service.
|
||||
Set the ``ngx-public-mdb-port.targetPort`` to the port number on which the
|
||||
Kubernetes MongoDB service will be present.
|
||||
|
||||
* Set ``ngx-public-api-port.port`` to 80, or the port number on which you want to
|
||||
expose BigchainDB API service.
|
||||
Set the ``ngx-public-api-port.targetPort`` to the port number on which the
|
||||
Kubernetes BigchainDB API service will present.
|
||||
|
||||
* Set ``ngx-public-ws-port.port`` to 81, or the port number on which you want to
|
||||
expose BigchainDB Websocket service.
|
||||
Set the ``ngx-public-ws-port.targetPort`` to the port number on which the
|
||||
BigchainDB Websocket service will be present.
|
||||
|
||||
* Start the Kubernetes Service:
|
||||
|
||||
.. code:: bash
|
||||
@@ -138,20 +153,44 @@ Step 4.1: Vanilla NGINX
|
||||
|
||||
Step 4.2: OpenResty NGINX + 3scale
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* This configuration is located in the file ``nginx/nginx-3scale-svc.yaml``.
|
||||
|
||||
* You have to enable HTTPS for this one and will need an HTTPS certificate
|
||||
for your domain
|
||||
for your domain.
|
||||
|
||||
* You should have already created the Kubernetes Secret in the previous
|
||||
step.
|
||||
* You should have already created the necessary Kubernetes Secrets in the previous
|
||||
step (e.g. ``https-certs`` and ``threescale-credentials``).
|
||||
|
||||
* This configuration is located in the file ``nginx-3scale/nginx-3scale-svc.yaml``.
|
||||
|
||||
* Set the ``metadata.name`` and ``metadata.labels.name`` to the value
|
||||
set in ``ngx-instance-name`` in the ConfigMap above.
|
||||
|
||||
* Set the ``spec.selector.app`` to the value set in ``ngx-instance-name`` in
|
||||
the ConfigMap followed by ``-dep``. For example, if the value set in the
|
||||
``ngx-instance-name`` is ``ngx-instance-0``, set the
|
||||
``spec.selector.app`` to ``ngx-instance-0-dep``.
|
||||
|
||||
* Set ``ngx-public-mdb-port.port`` to 27017, or the port number on which you
|
||||
want to expose MongoDB service.
|
||||
Set the ``ngx-public-mdb-port.targetPort`` to the port number on which the
|
||||
Kubernetes MongoDB service will be present.
|
||||
|
||||
* Set ``ngx-public-3scale-port.port`` to 8080, or the port number on which
|
||||
you want to let 3scale communicate with Openresty NGINX for authenctication.
|
||||
Set the ``ngx-public-3scale-port.targetPort`` to the port number on which
|
||||
this Openresty NGINX service will be listening to for communication with
|
||||
3scale.
|
||||
|
||||
* Set ``ngx-public-bdb-port.port`` to 443, or the port number on which you want
|
||||
to expose BigchainDB API service.
|
||||
Set the ``ngx-public-api-port.targetPort`` to the port number on which the
|
||||
Kubernetes BigchainDB API service will present.
|
||||
|
||||
* Set ``ngx-public-bdb-port-http.port`` to 80, or the port number on which you
|
||||
want to expose BigchainDB Websocket service.
|
||||
Set the ``ngx-public-bdb-port-http.targetPort`` to the port number on which the
|
||||
BigchainDB Websocket service will be present.
|
||||
|
||||
* Start the Kubernetes Service:
|
||||
|
||||
.. code:: bash
|
||||
@@ -167,20 +206,18 @@ Step 5: Assign DNS Name to the NGINX Public IP
|
||||
<https://docs.bigchaindb.com/en/latest/terminology.html>`_ or are using
|
||||
HTTPS certificates tied to a domain.
|
||||
|
||||
* The following command can help you find out if the nginx service started
|
||||
* The following command can help you find out if the NGINX service started
|
||||
above has been assigned a public IP or external IP address:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ kubectl --context k8s-bdb-test-cluster-0 get svc -w
|
||||
|
||||
* Once a public IP is assigned, you can log in to the Azure portal and map it to
|
||||
* Once a public IP is assigned, you can map it to
|
||||
a DNS name.
|
||||
|
||||
* We usually assign ``bdb-test-cluster-0``, ``bdb-test-cluster-1`` and
|
||||
We usually assign ``bdb-test-cluster-0``, ``bdb-test-cluster-1`` and
|
||||
so on in our documentation.
|
||||
|
||||
* Let us assume that we assigned the unique name of ``bdb-test-cluster-0`` here.
|
||||
Let's assume that we assign the unique name of ``bdb-test-cluster-0`` here.
|
||||
|
||||
|
||||
**Set up DNS mapping in Azure.**
|
||||
@@ -195,7 +232,7 @@ have the Azure DNS prefix name along with a long random string, without the
|
||||
(for example, ``bdb-test-cluster-0``), click ``Save``, and wait for the
|
||||
changes to be applied.
|
||||
|
||||
To verify the DNS setting is operational, you can run ``nslookup <dns
|
||||
To verify the DNS setting is operational, you can run ``nslookup <DNS
|
||||
name added in ConfigMap>`` from your local Linux shell.
|
||||
|
||||
This will ensure that when you scale the replica set later, other MongoDB
|
||||
@@ -276,12 +313,6 @@ Step 8.1: Vanilla NGINX
|
||||
``BIGCHAINDB_BACKEND_HOST`` env var to
|
||||
``bdb-instance-0.default.svc.cluster.local``.
|
||||
|
||||
* Set ``MONGODB_FRONTEND_PORT`` to 27017, or the port number on which you
|
||||
want to expose MongoDB service.
|
||||
|
||||
* Set ``BIGCHAINDB_FRONTEND_PORT`` to 80, or the port number on which you
|
||||
want to expose BigchainDB service.
|
||||
|
||||
* Start the Kubernetes Deployment:
|
||||
|
||||
.. code:: bash
|
||||
@@ -314,12 +345,6 @@ Step 8.2: OpenResty NGINX + 3scale
|
||||
``BIGCHAINDB_BACKEND_HOST`` env var to
|
||||
``bdb-instance-0.default.svc.cluster.local``.
|
||||
|
||||
* Set ``MONGODB_FRONTEND_PORT`` to 27017, or the port number on which you
|
||||
want to expose the MongoDB service.
|
||||
|
||||
* Set ``BIGCHAINDB_FRONTEND_PORT`` to 443, or the port number on which you
|
||||
want to expose the BigchainDB service over HTTPS.
|
||||
|
||||
* Start the Kubernetes Deployment:
|
||||
|
||||
.. code:: bash
|
||||
@@ -452,11 +477,11 @@ Step 11: Start a Kubernetes StatefulSet for MongoDB
|
||||
|
||||
* Note how the MongoDB container uses the ``mongo-db-claim`` and the
|
||||
``mongo-configdb-claim`` PersistentVolumeClaims for its ``/data/db`` and
|
||||
``/data/configdb`` diretories (mount path).
|
||||
``/data/configdb`` directories (mount paths).
|
||||
|
||||
* Note also that we use the pod's ``securityContext.capabilities.add``
|
||||
specification to add the ``FOWNER`` capability to the container. That is
|
||||
because MongoDB container has the user ``mongodb``, with uid ``999`` and
|
||||
because the MongoDB container has the user ``mongodb``, with uid ``999`` and
|
||||
group ``mongodb``, with gid ``999``.
|
||||
When this container runs on a host with a mounted disk, the writes fail
|
||||
when there is no user with uid ``999``. To avoid this, we use the Docker
|
||||
@@ -487,7 +512,135 @@ Step 11: Start a Kubernetes StatefulSet for MongoDB
|
||||
$ kubectl --context k8s-bdb-test-cluster-0 get pods -w
|
||||
|
||||
|
||||
Step 12: Start a Kubernetes Deployment for MongoDB Monitoring Agent
|
||||
Step 12: Configure Users and Access Control for MongoDB
|
||||
-------------------------------------------------------
|
||||
|
||||
* In this step, you will create a user on MongoDB with authorization
|
||||
to create more users and assign
|
||||
roles to them.
|
||||
Note: You need to do this only when setting up the first MongoDB node of
|
||||
the cluster.
|
||||
|
||||
* Find out the name of your MongoDB pod by reading the output
|
||||
of the ``kubectl ... get pods`` command at the end of the last step.
|
||||
It should be something like ``mdb-instance-0-ss-0``.
|
||||
|
||||
* Log in to the MongoDB pod using:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ kubectl --context k8s-bdb-test-cluster-0 exec -it <name of your MongoDB pod> bash
|
||||
|
||||
* Open a mongo shell using the certificates
|
||||
already present at ``/etc/mongod/ssl/``
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ mongo --host localhost --port 27017 --verbose --ssl \
|
||||
--sslCAFile /etc/mongod/ssl/ca.pem \
|
||||
--sslPEMKeyFile /etc/mongod/ssl/mdb-instance.pem
|
||||
|
||||
* Initialize the replica set using:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
> rs.initiate( {
|
||||
_id : "bigchain-rs",
|
||||
members: [ {
|
||||
_id : 0,
|
||||
host :"<hostname>:27017"
|
||||
} ]
|
||||
} )
|
||||
|
||||
The ``hostname`` in this case will be the value set in
|
||||
``mdb-instance-name`` in the ConfigMap.
|
||||
For example, if the value set in the ``mdb-instance-name`` is
|
||||
``mdb-instance-0``, set the ``hostname`` above to the value ``mdb-instance-0``.
|
||||
|
||||
* The instance should be voted as the ``PRIMARY`` in the replica set (since
|
||||
this is the only instance in the replica set till now).
|
||||
This can be observed from the mongo shell prompt,
|
||||
which will read ``PRIMARY>``.
|
||||
|
||||
* Create a user ``adminUser`` on the ``admin`` database with the
|
||||
authorization to create other users. This will only work the first time you
|
||||
log in to the mongo shell. For further details, see `localhost
|
||||
exception <https://docs.mongodb.com/manual/core/security-users/#localhost-exception>`_
|
||||
in MongoDB.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
PRIMARY> use admin
|
||||
PRIMARY> db.createUser( {
|
||||
user: "adminUser",
|
||||
pwd: "superstrongpassword",
|
||||
roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
|
||||
} )
|
||||
|
||||
* Exit and restart the mongo shell using the above command.
|
||||
Authenticate as the ``adminUser`` we created earlier:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
PRIMARY> use admin
|
||||
PRIMARY> db.auth("adminUser", "superstrongpassword")
|
||||
|
||||
``db.auth()`` returns 0 when authentication is not successful,
|
||||
and 1 when successful.
|
||||
|
||||
* We need to specify the user name *as seen in the certificate* issued to
|
||||
the BigchainDB instance in order to authenticate correctly. Use
|
||||
the following ``openssl`` command to extract the user name from the
|
||||
certificate:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ openssl x509 -in <path to the bigchaindb certificate> \
|
||||
-inform PEM -subject -nameopt RFC2253
|
||||
|
||||
You should see an output line that resembles:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
subject= emailAddress=dev@bigchaindb.com,CN=test-bdb-ssl,OU=BigchainDB-Instance,O=BigchainDB GmbH,L=Berlin,ST=Berlin,C=DE
|
||||
|
||||
The ``subject`` line states the complete user name we need to use for
|
||||
creating the user on the mongo shell as follows:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
PRIMARY> db.getSiblingDB("$external").runCommand( {
|
||||
createUser: 'emailAddress=dev@bigchaindb.com,CN=test-bdb-ssl,OU=BigchainDB-Instance,O=BigchainDB GmbH,L=Berlin,ST=Berlin,C=DE',
|
||||
writeConcern: { w: 'majority' , wtimeout: 5000 },
|
||||
roles: [
|
||||
{ role: 'clusterAdmin', db: 'admin' },
|
||||
{ role: 'readWriteAnyDatabase', db: 'admin' }
|
||||
]
|
||||
} )
|
||||
|
||||
* You can similarly create users for MongoDB Monitoring Agent and MongoDB
|
||||
Backup Agent. For example:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
PRIMARY> db.getSiblingDB("$external").runCommand( {
|
||||
createUser: 'emailAddress=dev@bigchaindb.com,CN=test-mdb-mon-ssl,OU=MongoDB-Mon-Instance,O=BigchainDB GmbH,L=Berlin,ST=Berlin,C=DE',
|
||||
writeConcern: { w: 'majority' , wtimeout: 5000 },
|
||||
roles: [
|
||||
{ role: 'clusterMonitor', db: 'admin' }
|
||||
]
|
||||
} )
|
||||
|
||||
PRIMARY> db.getSiblingDB("$external").runCommand( {
|
||||
createUser: 'emailAddress=dev@bigchaindb.com,CN=test-mdb-bak-ssl,OU=MongoDB-Bak-Instance,O=BigchainDB GmbH,L=Berlin,ST=Berlin,C=DE',
|
||||
writeConcern: { w: 'majority' , wtimeout: 5000 },
|
||||
roles: [
|
||||
{ role: 'backup', db: 'admin' }
|
||||
]
|
||||
} )
|
||||
|
||||
|
||||
Step 13: Start a Kubernetes Deployment for MongoDB Monitoring Agent
|
||||
-------------------------------------------------------------------
|
||||
|
||||
* This configuration is located in the file
|
||||
@@ -508,7 +661,7 @@ Step 12: Start a Kubernetes Deployment for MongoDB Monitoring Agent
|
||||
$ kubectl --context k8s-bdb-test-cluster-0 apply -f mongodb-monitoring-agent/mongo-mon-dep.yaml
|
||||
|
||||
|
||||
Step 13: Start a Kubernetes Deployment for MongoDB Backup Agent
|
||||
Step 14: Start a Kubernetes Deployment for MongoDB Backup Agent
|
||||
---------------------------------------------------------------
|
||||
|
||||
* This configuration is located in the file
|
||||
@@ -529,7 +682,7 @@ Step 13: Start a Kubernetes Deployment for MongoDB Backup Agent
|
||||
$ kubectl --context k8s-bdb-test-cluster-0 apply -f mongodb-backup-agent/mongo-backup-dep.yaml
|
||||
|
||||
|
||||
Step 14: Start a Kubernetes Deployment for Bigchaindb
|
||||
Step 15: Start a Kubernetes Deployment for Bigchaindb
|
||||
-----------------------------------------------------
|
||||
|
||||
* This configuration is located in the file
|
||||
@@ -569,7 +722,7 @@ Step 14: Start a Kubernetes Deployment for Bigchaindb
|
||||
* You can check its status using the command ``kubectl get deploy -w``
|
||||
|
||||
|
||||
Step 15: Configure the MongoDB Cloud Manager
|
||||
Step 16: Configure the MongoDB Cloud Manager
|
||||
--------------------------------------------
|
||||
|
||||
* Refer to the
|
||||
@@ -578,10 +731,10 @@ Step 15: Configure the MongoDB Cloud Manager
|
||||
monitoring and backup.
|
||||
|
||||
|
||||
Step 16: Verify the BigchainDB Node Setup
|
||||
Step 17: Verify the BigchainDB Node Setup
|
||||
-----------------------------------------
|
||||
|
||||
Step 16.1: Testing Internally
|
||||
Step 17.1: Testing Internally
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Run a container that provides utilities like ``nslookup``, ``curl`` and ``dig``
|
||||
@@ -670,7 +823,7 @@ themselves.
|
||||
* Send some transactions to BigchainDB and verify it's up and running!
|
||||
|
||||
|
||||
Step 16.2: Testing Externally
|
||||
Step 17.2: Testing Externally
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Try to access the ``<dns/ip of your exposed bigchaindb service endpoint>:80``
|
||||
|
||||
@@ -39,3 +39,5 @@ Generate a new CRL for your infrastructure using:
|
||||
|
||||
The generated ``crl.pem`` file needs to be uploaded to your infrastructure to
|
||||
prevent the revoked certificate from being used again.
|
||||
|
||||
In particlar, the generated ``crl.pem`` file should be sent to all BigchainDB node operators in your BigchainDB cluster, so that they can update it in their MongoDB instance and their BigchainDB Server instance.
|
||||
|
||||
@@ -26,7 +26,7 @@ Step 2: Create the Server Private Key and CSR
|
||||
---------------------------------------------
|
||||
|
||||
You can create the server private key and certificate signing request (CSR)
|
||||
by going into the directory ``member-cert/easy-rsa-3.0.1/easyrsa``
|
||||
by going into the directory ``member-cert/easy-rsa-3.0.1/easyrsa3``
|
||||
and using something like:
|
||||
|
||||
.. code:: bash
|
||||
@@ -35,15 +35,17 @@ and using something like:
|
||||
|
||||
./easyrsa --req-cn=mdb-instance-0 --subject-alt-name=DNS:localhost,DNS:mdb-instance-0 gen-req mdb-instance-0 nopass
|
||||
|
||||
You will be prompted to enter the Distinguished Name for this certificate. You
|
||||
can hit enter to accept the default values or change them at each prompt.
|
||||
You should replace the Common Name (``mdb-instance-0`` above) with the correct name for *your* MongoDB instance in the cluster, e.g. ``mdb-instance-5`` or ``mdb-instance-12``. (This name is decided by the organization managing the cluster.)
|
||||
|
||||
You can replace the common name (``mdb-instance-0`` above) with any other name
|
||||
so long as the instance can verify that it is the hostname.
|
||||
You will be prompted to enter the Distinguished Name (DN) information for this certificate.
|
||||
For each field, you can accept the default value [in brackets] by pressing Enter.
|
||||
|
||||
You need to provide the ``DNS:localhost`` SAN during certificate generation
|
||||
.. warning::
|
||||
|
||||
Don't accept the default value of OU (``IT``). Instead, enter the value ``MongoDB-Instance``.
|
||||
|
||||
Aside: You need to provide the ``DNS:localhost`` SAN during certificate generation
|
||||
for using the ``localhost exception`` in the MongoDB instance.
|
||||
|
||||
All certificates can have this attribute without compromising security as the
|
||||
``localhost exception`` works only the first time.
|
||||
|
||||
@@ -51,15 +53,18 @@ All certificates can have this attribute without compromising security as the
|
||||
Step 3: Get the Server Certificate Signed
|
||||
-----------------------------------------
|
||||
|
||||
The CSR file (created in the last step)
|
||||
should be located in ``pki/reqs/mdb-instance-0.req``.
|
||||
The CSR file created in the last step
|
||||
should be located in ``pki/reqs/mdb-instance-0.req``
|
||||
(where the integer ``0`` may be different for you).
|
||||
You need to send it to the organization managing the cluster
|
||||
so that they can use their CA
|
||||
to sign the request.
|
||||
(The managing organization should already have a self-signed CA.)
|
||||
|
||||
If you are the admin of the managing organization's self-signed CA,
|
||||
then you can import the CSR and use Easy-RSA to sign it. For example:
|
||||
then you can import the CSR and use Easy-RSA to sign it.
|
||||
Go to your ``bdb-cluster-ca/easy-rsa-3.0.1/easyrsa3/``
|
||||
directory and do something like:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
|
||||
@@ -102,7 +102,7 @@ Finally, you can deploy an ACS using something like:
|
||||
--agent-vm-size Standard_D2_v2 \
|
||||
--dns-prefix <make up a name> \
|
||||
--ssh-key-value ~/.ssh/<name>.pub \
|
||||
--orchestrator-type kubernetes
|
||||
--orchestrator-type kubernetes \
|
||||
--debug --output json
|
||||
|
||||
|
||||
|
||||
@@ -53,6 +53,26 @@ Similarly, other instances must also have unique names in the cluster.
|
||||
#. Name of the MongoDB backup agent instance (``mdb-bak-instance-*``)
|
||||
|
||||
|
||||
☐ Generate four keys and corresponding certificate signing requests (CSRs):
|
||||
|
||||
#. Server Certificate (a.k.a. Member Certificate) for the MongoDB instance
|
||||
#. Client Certificate for BigchainDB Server to identify itself to MongoDB
|
||||
#. Client Certificate for MongoDB Monitoring Agent to identify itself to MongoDB
|
||||
#. Client Certificate for MongoDB Backup Agent to identify itself to MongoDB
|
||||
|
||||
Ask the managing organization to use its self-signed CA to sign those four CSRs.
|
||||
They should send you:
|
||||
|
||||
* Four certificates (one for each CSR you sent them).
|
||||
* One ``ca.crt`` file: their CA certificate.
|
||||
* One ``crl.pem`` file: a certificate revocation list.
|
||||
|
||||
For help, see the pages:
|
||||
|
||||
* :ref:`How to Generate a Server Certificate for MongoDB`
|
||||
* :ref:`How to Generate a Client Certificate for MongoDB`
|
||||
|
||||
|
||||
☐ Every node in a BigchainDB cluster needs its own
|
||||
BigchainDB keypair (i.e. a public key and corresponding private key).
|
||||
You can generate a BigchainDB keypair for your node, for example,
|
||||
@@ -73,29 +93,17 @@ Don't share your private key.
|
||||
That list of public keys is known as the BigchainDB "keyring."
|
||||
|
||||
|
||||
☐ Ask the managing organization
|
||||
for the FQDN used to serve the BigchainDB APIs
|
||||
(e.g. ``api.orgname.net`` or ``bdb.clustername.com``).
|
||||
|
||||
|
||||
☐ Make up an FQDN for your BigchainDB node (e.g. ``mynode.mycorp.com``).
|
||||
Make sure you've registered the associated domain name (e.g. ``mycorp.com``),
|
||||
and have an SSL certificate for the FQDN.
|
||||
(You can get an SSL certificate from any SSL certificate provider).
|
||||
|
||||
|
||||
☐ Share your BigchaindB *public* key with all the other nodes
|
||||
in the BigchainDB cluster.
|
||||
Don't share your private key.
|
||||
|
||||
|
||||
☐ Get the BigchainDB public keys of all the other nodes in the cluster.
|
||||
That list of public keys is known as the BigchainDB "keyring."
|
||||
(You can get an SSL certificate from any SSL certificate provider.)
|
||||
|
||||
|
||||
☐ Ask the managing organization
|
||||
for the FQDN used to serve the BigchainDB APIs
|
||||
(e.g. ``api.orgname.net`` or ``bdb.clustername.com``)
|
||||
and for a copy of the associated SSL/TLS certificate.
|
||||
Also, ask for the user name to use for authenticating to MongoDB.
|
||||
|
||||
|
||||
☐ If the cluster uses 3scale for API authentication, monitoring and billing,
|
||||
@@ -112,37 +120,11 @@ allow easier periodic rotation of the ``Agent API Key`` with a constant
|
||||
``Group ID``)
|
||||
|
||||
|
||||
☐ Generate four keys and corresponding certificate signing requests (CSRs):
|
||||
|
||||
#. Server Certificate (a.k.a. Member Certificate) for the MongoDB instance
|
||||
#. Client Certificate for BigchainDB Server to identify itself to MongoDB
|
||||
#. Client Certificate for MongoDB Monitoring Agent to identify itself to MongoDB
|
||||
#. Client Certificate for MongoDB Backup Agent to identify itself to MongoDB
|
||||
#. CRL for the infrastructure to not accept revoked certificates.
|
||||
|
||||
Ask the managing organization to use its self-signed CA to sign those certificates.
|
||||
|
||||
For help, see the pages:
|
||||
|
||||
* :ref:`How to Generate a Server Certificate for MongoDB`
|
||||
* :ref:`How to Generate a Client Certificate for MongoDB`
|
||||
|
||||
|
||||
☐ :doc:`Deploy a Kubernetes cluster on Azure <template-kubernetes-azure>`.
|
||||
|
||||
|
||||
☐ Create the Kubernetes Configuration for this node.
|
||||
We will use Kubernetes ConfigMaps and Secrets to hold all the information
|
||||
gathered above.
|
||||
|
||||
|
||||
☐ Deploy your BigchainDB node on your Kubernetes cluster.
|
||||
|
||||
Next Steps To Set Up a Node
|
||||
---------------------------
|
||||
|
||||
You can now proceed to set up your BigchainDB node based on whether it is the
|
||||
:ref:`first node in you cluster
|
||||
☐ You can now proceed to set up your BigchainDB node based on whether it is the
|
||||
:ref:`first node in a new cluster
|
||||
<Kubernetes Template: Deploy a Single BigchainDB Node>` or a
|
||||
:ref:`node that will be added to an existing cluster
|
||||
<Kubernetes Template: Add a BigchainDB Node to an Existing BigchainDB Cluster>`.
|
||||
|
||||
@@ -21,7 +21,6 @@ For convenience, here's a list of all the relevant environment variables (docume
|
||||
`BIGCHAINDB_SERVER_BIND`<br>
|
||||
`BIGCHAINDB_SERVER_LOGLEVEL`<br>
|
||||
`BIGCHAINDB_SERVER_WORKERS`<br>
|
||||
`BIGCHAINDB_SERVER_THREADS`<br>
|
||||
`BIGCHAINDB_WSSERVER_SCHEME`<br>
|
||||
`BIGCHAINDB_WSSERVER_HOST`<br>
|
||||
`BIGCHAINDB_WSSERVER_PORT`<br>
|
||||
@@ -45,6 +44,7 @@ For convenience, here's a list of all the relevant environment variables (docume
|
||||
`BIGCHAINDB_DATABASE_KEYFILE`<br>
|
||||
`BIGCHAINDB_DATABASE_KEYFILE_PASSPHRASE`<br>
|
||||
`BIGCHAINDB_DATABASE_CRLFILE`<br>
|
||||
`BIGCHAINDB_GRAPHITE_HOST`<br>
|
||||
|
||||
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`.
|
||||
@@ -52,7 +52,7 @@ Note that the `-c` command line option will always take precedence if both the `
|
||||
|
||||
You can read the current default values in the file [bigchaindb/\_\_init\_\_.py](https://github.com/bigchaindb/bigchaindb/blob/master/bigchaindb/__init__.py). (The link is to the latest version.)
|
||||
|
||||
Running `bigchaindb -y configure rethinkdb` 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`).
|
||||
Running `bigchaindb -y configure mongodb` will generate a local config file in `$HOME/.bigchaindb` with all the default values (for using MongoDB as the database backend), with two exceptions: it will generate a valid private/public keypair, rather than using the default keypair (`None` and `None`).
|
||||
|
||||
|
||||
## keypair.public & keypair.private
|
||||
@@ -73,7 +73,7 @@ export BIGCHAINDB_KEYPAIR_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 rethinkdb`.
|
||||
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 mongodb`.
|
||||
|
||||
|
||||
## keyring
|
||||
@@ -102,12 +102,12 @@ Note how the keys in the list are separated by colons.
|
||||
## database.*
|
||||
|
||||
The settings with names of the form `database.*` are for the database backend
|
||||
(currently either RethinkDB or MongoDB). They are:
|
||||
(currently either MongoDB or RethinkDB). They are:
|
||||
|
||||
* `database.backend` is either `rethinkdb` or `mongodb`.
|
||||
* `database.backend` is either `mongodb` or `rethinkdb`.
|
||||
* `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.name` is a user-chosen name for the database inside MongoDB or RethinkDB, 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.
|
||||
* `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.
|
||||
@@ -176,20 +176,19 @@ If you used `bigchaindb -y configure mongodb` to create a default local config f
|
||||
|
||||
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.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). Each worker process has a single thread. The HTTP server will be able to handle `server.workers` requests simultaneously.
|
||||
`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 (2 × cpu_count + 1). Each worker process has a single thread. The HTTP server will be able to handle `server.workers` 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
|
||||
```
|
||||
|
||||
**Example config file snippet**
|
||||
@@ -211,12 +210,14 @@ export BIGCHAINDB_SERVER_THREADS=5
|
||||
```
|
||||
|
||||
|
||||
## wsserver.host and wsserver.port
|
||||
## wsserver.scheme, wsserver.host and wsserver.port
|
||||
|
||||
These settings are for the
|
||||
[aiohttp server](https://aiohttp.readthedocs.io/en/stable/index.html),
|
||||
which is used to serve the
|
||||
[WebSocket Event Stream API](../websocket-event-stream-api.html).
|
||||
`wsserver.scheme` should be either `"ws"` or `"wss"`
|
||||
(but setting it to `"wss"` does *not* enable SSL/TLS).
|
||||
`wsserver.host` is where to bind the aiohttp server socket and
|
||||
`wsserver.port` is the corresponding port.
|
||||
If you want to allow connections from anyone, on port 9985,
|
||||
@@ -224,6 +225,7 @@ set `wsserver.host` to 0.0.0.0 and `wsserver.port` to 9985.
|
||||
|
||||
**Example using environment variables**
|
||||
```text
|
||||
export BIGCHAINDB_WSSERVER_SCHEME=ws
|
||||
export BIGCHAINDB_WSSERVER_HOST=0.0.0.0
|
||||
export BIGCHAINDB_WSSERVER_PORT=9985
|
||||
```
|
||||
@@ -231,6 +233,7 @@ export BIGCHAINDB_WSSERVER_PORT=9985
|
||||
**Example config file snippet**
|
||||
```js
|
||||
"wsserver": {
|
||||
"scheme": "wss",
|
||||
"host": "0.0.0.0",
|
||||
"port": 65000
|
||||
}
|
||||
@@ -239,6 +242,7 @@ export BIGCHAINDB_WSSERVER_PORT=9985
|
||||
**Default values (from a config file)**
|
||||
```js
|
||||
"wsserver": {
|
||||
"scheme": "ws",
|
||||
"host": "localhost",
|
||||
"port": 9985
|
||||
}
|
||||
@@ -492,3 +496,29 @@ logging of the `core.py` module to be more verbose, you would set the
|
||||
```
|
||||
|
||||
**Defaults to**: `"{}"`
|
||||
|
||||
|
||||
## graphite.host
|
||||
|
||||
The host name or IP address of a server listening for statsd events on UDP
|
||||
port 8125. This defaults to `localhost`, and if no statsd collector is running,
|
||||
the events are simply dropped by the operating system.
|
||||
|
||||
**Example using environment variables**
|
||||
```text
|
||||
export BIGCHAINDB_GRAPHITE_HOST=10.0.0.5
|
||||
```
|
||||
|
||||
**Example config file snippet**
|
||||
```js
|
||||
"graphite": {
|
||||
"host": "10.0.0.5"
|
||||
}
|
||||
```
|
||||
|
||||
**Default values (from a config file)**
|
||||
```js
|
||||
"graphite": {
|
||||
"host": "localhost"
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user