Setting up your node for a network

After you managed to start your node using either docker or native it’s time to connect to a network.

Prerequisites

The following is needed to connect a Nuts node to a network:

A runnable node.
The public address of one or more remote nodes you’d like to use as bootstrap nodes.
A TLS client- and server certificate which is accepted by the other nodes in the network (e.g. PKIoverheid).
A truststore containing the CA trust anchors for TLS certificates the network you’re connecting to accepts (e.g. PKIoverheid).

To connect to the development network you can use the nuts-development-network-ca by cloning https://github.com/nuts-foundation/nuts-development-network-ca. That project contains scripts to generate certificates, and a truststore.

Configuring

Configure the bootstrap nodes using network.bootstrapnodes.
Configure TLS using network.certfile, network.certkeyfile and network.truststorefile.

See configuration reference for a detailed explanation on how to exactly configure the Nuts node.

Note

You _can_ start the node without configuring the network, but it won’t connect and thus exchange data with other nodes.

YAML Configuration File

If you’re using a YAML file to configure your node, the following snippet shows an example for the network related configuration:

network:
  truststorefile: /path/to/truststore.pem
  certfile: /path/to/certificate-and-key.pem
  certkeyfile: /path/to/certificate-and-key.pem
  bootstrapnodes:
    - example.com:5555

Node TLS Certificate

To connect to an existing Nuts network you need a TLS certificate which authenticates your node. For the development network you can use the nuts-network-development-ca to directly issue a certificate for your node. The commands below clone the required Git repository, generate a private key and issues a certificate, and combines them into a single file:

git clone https://github.com/nuts-foundation/nuts-development-network-ca
cd nuts-development-network-ca && ./issue-cert.sh localhost
cat localhost.key localhost.pem > certificate-and-key.pem

Note

If you want peers to be able to connect to your node, replace localhost with the correct hostname.

Note that the Git repository contains the Certificate Authority certificate (ca.pem) which will function as truststore. Copy this file as truststore.pem into the working directory.

Node Identity

Certain data (e.g. private credentials) can only be exchanged when a peer’s DID has been authenticated. To make sure other nodes can authenticate your node’s DID you need to configure your node’s identity, and make sure the DID document contains a NutsComm service that matches the TLS certificate.

Your node identity is expressed by a DID that is managed by your node, also known as your vendor DID. So make sure you have created a DID specific for your nodes and configure it as network.nodedid (see configuration reference).

Then you make sure the associated DID Document contains a NutsComm endpoint, where the domain part (e.g. nuts.nl) matches (one of) the DNS SANs in your node’s TLS certificate. See “Node Discovery” below for more information on registering the NutsComm endpoint.

Note

Multiple nodes may share the same DID, if they’re governed by the same organization (e.g., clustered setups).

Node Discovery

To allow your Nuts node to be discovered by other nodes, so they can connect to it, you need to register a NutsComm endpoint on your vendor DID document. The NutsComm endpoint contains a URL to your node’s public gRPC service, and must be in the form of grpc://<host>:<port>. E.g., if it were to run on nuts.nl:5555, the value of the NutsComm endpoint should be grpc://nuts.nl:5555

You can register the NutsComm endpoint by calling addEndpoint on the DIDMan API:

POST <internal-node-address>/internal/didman/v1/did/<vendor-did>/endpoint
{
    "type": "NutsComm",
    "endpoint": "grpc://nuts.nl:5555"
}

Care Organizations

The DID documents of your care organizations you (as a vendor) want to expose on the Nuts network need to be associated with your vendor’s DID document through the NutsComm endpoint. Its recommended to register the actual NutsComm endpoint on your vendor DID document (as explained in the previous section), and register a reference to this endpoint on the DID documents of your vendor’s care organizations:

POST <internal-node-address>/internal/didman/v1/did/<care-organization-did>/endpoint
{
    "type": "NutsComm",
    "endpoint": "<vendor-did>/serviceEndpoint?type=NutsComm"
}