nuts-node

README

nuts-node
#########

Distributed registry for storing and querying health care providers their vendors and technical endpoints.

.. image:: https://circleci.com/gh/nuts-foundation/nuts-node.svg?style=svg
    :target: https://circleci.com/gh/nuts-foundation/nuts-node
    :alt: Build Status

.. image:: https://readthedocs.org/projects/nuts-node/badge/?version=latest
    :target: https://nuts-node.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. image:: https://api.codeclimate.com/v1/badges/69f77bd34f3ac253cae0/test_coverage
    :target: https://codeclimate.com/github/nuts-foundation/nuts-node/test_coverage
    :alt: Code coverage

.. image:: https://api.codeclimate.com/v1/badges/69f77bd34f3ac253cae0/maintainability
   :target: https://codeclimate.com/github/nuts-foundation/nuts-node/maintainability
   :alt: Maintainability

.. image:: https://github.com/nuts-foundation/nuts-node/actions/workflows/build-images.yaml/badge.svg
   :target: https://github.com/nuts-foundation/nuts-node/actions/workflows/build-images.yaml
   :alt: Build Docker images

Requirements
************

Go >= 1.17 is required.

Building
********

Just use ``go build``.

Running tests
*************

Tests can be run by executing

.. code-block:: shell

    go test ./...

Code Generation
***************

Code generation is used for generating mocks, OpenAPI client- and servers, and gRPC services.
Make sure that ``GOPATH/bin`` is available on ``PATH`` and that the dependencies are installed

Install ``protoc``:

  | MacOS: ``brew install protobuf``
  | Linux: ``apt install -y protobuf-compiler``

Install Go tools:

.. code-block:: shell

  make install-tools

Generating code:

To regenerate all code run the ``run-generators`` target from the makefile or use one of the following for a specific group

================ =======================
Group            Command
================ =======================
Mocks            ``make gen-mocks``
OpenApi          ``make gen-api``
Protobuf + gRCP  ``make gen-protobuf``
All              ``make run-generators``
================ =======================

Docs Generation
***************

To generate the documentation, you'll need ``python3``, ``sphinx`` and a bunch of other stuff.
After you have installed ``python3`` (and ``pip3`` if this not already installed) run

.. code-block:: shell

    pip3 install -r docs/requirements.txt


README
======

The readme is auto-generated from a template and uses the documentation to fill in the blanks.

.. code-block:: shell

    make gen-readme

Documentation
=============

The documentation can be build by running the following command from the ``/docs`` directory:

.. code-block:: shell

    make html

Configuration
*************

The Nuts node can be configured using a YAML configuration file, environment variables and commandline params.

The parameters follow the following convention:
``$ nuts --parameter X`` is equal to ``$ NUTS_PARAMETER=X nuts`` is equal to ``parameter: X`` in a yaml file.

Or for this piece of yaml

.. code-block:: yaml

    nested:
        parameter: X

is equal to ``$ nuts --nested.parameter X`` is equal to ``$ NUTS_NESTED_PARAMETER=X nuts``

Config parameters for engines are prepended by the ``engine.ConfigKey`` by default (configurable):

.. code-block:: yaml

    engine:
        nested:
            parameter: X

is equal to ``$ nuts --engine.nested.parameter X`` is equal to ``$ NUTS_ENGINE_NESTED_PARAMETER=X nuts``

While most options are a single value, some are represented as a list (indicated with the square brackets in the table below).
To provide multiple values through flags or environment variables you can separate them with a comma (``,``).

Ordering
********

Command line parameters have the highest priority, then environment variables, then parameters from the configfile and lastly defaults.
The location of the configfile is determined by the environment variable ``NUTS_CONFIGFILE`` or the commandline parameter ``--configfile``. If both are missing the default location ``./nuts.yaml`` is used.

Server options
**************

The following options can be configured on the server:

.. marker-for-config-options

=========================================  ================  ====================================================================================================================================================================================================================================
Key                                        Default           Description
=========================================  ================  ====================================================================================================================================================================================================================================
configfile                                 nuts.yaml         Nuts config file
datadir                                    ./data            Directory where the node stores its files.
loggerformat                               text              Log format (text, json)
strictmode                                 false             When set, insecure settings are forbidden.
verbosity                                  info              Log level (trace, debug, info, warn, error)
http.default.address                       \:1323             Address and port the server will be listening to
http.default.cors.origin                   []                When set, enables CORS from the specified origins for the on default HTTP interface.
**Auth**
auth.clockskew                             5000              Allowed JWT Clock skew in milliseconds
auth.contractvalidators                    [irma,uzi,dummy]  sets the different contract validators to use
auth.http.timeout                          30                HTTP timeout (in seconds) used by the Auth API HTTP client
auth.irma.autoupdateschemas                true              set if you want automatically update the IRMA schemas every 60 minutes.
auth.irma.schememanager                    pbdf              IRMA schemeManager to use for attributes. Can be either 'pbdf' or 'irma-demo'.
auth.publicurl                                               public URL which can be reached by a users IRMA client, this should include the scheme and domain: https://example.com. Additional paths should only be added if some sort of url-rewriting is done in a reverse-proxy.
**Crypto**
crypto.storage                             fs                Storage to use, 'fs' for file system, vaultkv for Vault KV store, default: fs.
crypto.vault.address                                         The Vault address. If set it overwrites the VAULT_ADDR env var.
crypto.vault.pathprefix                    kv                The Vault path prefix. default: kv.
crypto.vault.token                                           The Vault token. If set it overwrites the VAULT_TOKEN env var.
**Event manager**
events.nats.hostname                       localhost         Hostname for the NATS server
events.nats.port                           4222              Port where the NATS server listens on
events.nats.storagedir                                       Directory where file-backed streams are stored in the NATS server
events.nats.timeout                        30                Timeout for NATS server operations
**Network**
network.bootstrapnodes                     []                List of bootstrap nodes (`<host>:<port>`) which the node initially connect to.
network.certfile                                             PEM file containing the server certificate for the gRPC server. Required when `enableTLS` is `true`.
network.certkeyfile                                          PEM file containing the private key of the server certificate. Required when `network.enabletls` is `true`.
network.disablenodeauthentication          false             Disable node DID authentication using client certificate, causing all node DIDs to be accepted. Unsafe option, only intended for workshops/demo purposes. Not allowed in strict-mode.
network.enablediscovery                    true              Whether to enable automatic connecting to other nodes.
network.enabletls                          true              Whether to enable TLS for incoming and outgoing gRPC connections. When `certfile` or `certkeyfile` is specified it defaults to `true`, otherwise `false`.
network.grpcaddr                           \:5555             Local address for gRPC to listen on. If empty the gRPC server won't be started and other nodes will not be able to connect to this node (outbound connections can still be made).
network.nodedid                                              Specifies the DID of the organization that operates this node, typically a vendor for EPD software. It is used to identify the node on the network. If the DID document does not exist of is deactivated, the node will not start.
network.truststorefile                                       PEM file containing the trusted CA certificates for authenticating remote gRPC servers.
network.v1.advertdiagnosticsinterval       5000              Interval (in milliseconds) that specifies how often the node should broadcast its diagnostic information to other nodes (specify 0 to disable).
network.v1.adverthashesinterval            2000              Interval (in milliseconds) that specifies how often the node should broadcast its last hashes to other nodes.
network.v1.collectmissingpayloadsinterval  60000             Interval (in milliseconds) that specifies how often the node should check for missing payloads and broadcast its peers for it (specify 0 to disable). This check might be heavy on larger DAGs so make sure not to run it too often.
network.v2.gossipinterval                  5000              Interval (in milliseconds) that specifies how often the node should gossip its new hashes to other nodes.
**VCR**
vcr.overrideissueallpublic                 true              Overrides the "Public" property of a credential when issuing credentials: if set to true, all issued credentials are published as public credentials, regardless of whether they're actually marked as public.
=========================================  ================  ====================================================================================================================================================================================================================================

This table is automatically generated using the configuration flags in the core and engines. When they're changed
the options table must be regenerated using the Makefile:

.. code-block:: shell

    $ make update-docs

CLI options
***********

The following options can be supplied when running CLI commands:

=======  ==============  =====================================================================================================================================================================
Key      Default         Description
=======  ==============  =====================================================================================================================================================================
address  localhost:1323  Address of the remote node. Must contain at least host and port, URL scheme may be omitted. In that case it 'http://' is prepended.
timeout  10s             Client time-out when performing remote operations, such as '500ms' or '10s'. Refer to Golang's 'time.Duration' syntax for a more elaborate description of the syntax.
=======  ==============  =====================================================================================================================================================================