The Nuts node supports different backends for storage. This page describes the particulars of each backend and how to configure it.
The node does not automatically back up your data or keys. This is something you need to set up regardless the backend you use.
Clustering is not supported. Even if you use a backend that supports concurrent access (e.g. Redis), you can’t have multiple Nuts nodes use the same data storage.
Data is everything your node produces and stores, except private keys. It is also everything that is produced and published by other nodes in the network.
By default, all data (aside from private keys) is stored on disk using BBolt. You don’t need to configure anything to get it working, but don’t forget the backup procedure. If an alternative data store is configured (e.g. Redis), volatile data (projections that are generally quick to rebuild) is still stored in BBolt. You can back up volatile data, but it is not required.
If the node is configured to use Redis it stores all non-volatile data in the configured Redis server.
To use Redis, configure
You can configure username/password authentication using
If you need to prefix the keys (e.g. you have multiple Nuts nodes using the same Redis server) you can set
with an alphanumeric string. All keys written to Redis will then have that prefix followed by a separator.
You can connect to your Redis server over TLS by specifying a Redis connection URL in
The server’s certificate will be verified against the OS’ CA bundle.
Make sure to configure persistence for your Redis server.
Your node generates and stores private keys when you create DID documents or add new keys to it. Private keys are very sensitive, if you leak them others could alter your presence on the Nuts network and possibly worse. If you lose them you need to re-register your presence on the Nuts network, which could be very cumbersome. Thus, it’s very important the private key storage is both secure and reliable.
This is the default backend but not recommended for production. It stores keys unencrypted on disk. Make sure to include the directory in your backups and keep these in a safe place. If you want to use filesystem in strict mode, you have to set it explicitly, otherwise the node fails during startup.
This storage backend is the recommended way of storing secrets. It uses the Vault KV version 1 store.
The prefix defaults to
kv and can be configured using the
There needs to be a KV Secrets Engine (v1) enabled under this prefix path.
All private keys are stored under the path
Each key is stored under the kid, resulting in a full key path like
A Vault token must be provided by either configuring it using the config
crypto.vault.token or setting the VAULT_TOKEN environment variable.
The token must have a vault policy which has READ and WRITES rights on the path. In addition it needs to READ the token information “auth/token/lookup-self” which should be part of the default policy.
Migrating to Vault
Migrating your private keys from the filesystem to Vault is relatively easy: just upload the keys to Vault under
Alternatively you can use the
fs2vault crypto command, which takes the directory containing the private keys as argument (the example assumes the container is called nuts-node):
docker exec nuts-node nuts crypto fs2vault /opt/nuts/data/crypto
In any case, make sure the key-value secret engine exists before trying to migrate (default engine name is