Customising the card store
The default card store is the /home/username/.composer
directory on the host machine. Local wallets can be problematic for applications running in cloud environments, and it may be desired to have the card store at different directory location. By using custom wallets, users can control where business network cards and the certificates and private keys used for Hyperledger Fabric authentication are stored.
Architecture
Whenever a BusinessNetworkConnection
or AdminConnection
is made, it has an associated CardStore
. Each connection can be configured to use a specific CardStore
. In the Hyperledger Composer repository, there are two pre-configured options for stores:
composer-wallet-filesystem
composer-wallet-inmemory
Custom implementations can be written for any given backend database or object store, enabling the specification of a CardStore
that is in a non-default file location, a separate docker container, or hosted in a cloud based data store. The store configuration can be completed using either a configuration file, or by using environment variables.
Multiple cloud wallet implementations can be installed using global npm installs.
Configuring a custom wallet
There are two ways to define the configuration for a custom wallet: by using a .json
configuration file, or by defining environment variables.
Please note: any custom wallet implementation must include the
composer-wallet
prefix in the module name.
Using a configuration file
For production deployments, it is more useful to be able to configure the card store outside of the application,
Hyperledger Composer uses the standard configuration module config
. The configuration file is loaded from a sub-directory of the current working directory called config
. The default configuration file is called default.json
, the configuration file name can be changed using the NODE_ENV
environment variable.
For example here is a configuration for a cloud wallet implementation called composer-wallet-redis
{
"composer": {
"wallet": {
"type": "composer-wallet-redis",
"desc": "Uses a local redis instance,
"options": {
}
}
}
}
type
is the name of this moduledesc
is some text for the humans
Please note: Each connection will have a new instance of the card store specified. If these resolve to the same backend store, cards can be shared.
Using an environment variable
Specifying the details of a custom wallet on the command line via environment variables may be achieved by setting an environment variable containing the same information as the configuration file.
The following environment variable example uses the same format and data as the preceding configuration file.
export NODE_CONFIG={"composer":{"wallet":{"type":"composer-wallet-redis","desc":"Uses a local redis instance,"options":{}}}}
Any application that is in this shell will use the cloud wallets.
Configuring file system custom card stores
The location of the file system card store can be changed using a configuration file, through specification of a storePath
as one of the wallet options.
{
"composer": {
"wallet" : {
"type": "composer-wallet-filesystem",
"options" : {
"storePath" : "/my/network/location"
}
}
}
The same .json
snippet may be exported as an environment variable.
Configuring cloud based custom card stores
The following GitHub repositories contain implementations of cloud custom wallets using Redis and the IBM Cloud Object Store, respectively.
- composer-tools/composer-wallet-redis - provides a backing store using a Redis server
- composer-tools/composer-wallet-ibmcos - provides a backing store using the IBM Cloud Object Store. This has an S3 compatible API
- composer-tools/composer-wallet-cloudant - provides a backing store using the IBM Cloudant
Multiple cloud custom wallet implementations can be installed using global npm installs.
To migrate to these custom wallet solutions, refer to the README files of the relevant GitHub repository.
In a general sense, migrating to a cloud wallet implementation has three steps.
- Export the business network cards you wish to use in the cloud custom wallet.
- Change configuration to specify the cloud custom wallet.
- Import the business network cards into the cloud custom wallet.
The composer-wallet-filesystem
is the default card store and follows the same layout on disc, and by default is in the same location.
Some samples and test cases show the card stores being created programmatically. This is still possible and but is slightly different in terms of initial creation of the card store.
Using custom wallets with APIs
API CardStore configuration
Using the default location file system card store remains the default option within API calls. For instance:
adminConnection = new AdminConnection();
clientConnection = new BusinessNetworkConnection();
will use the file system card store at the location /home/username/.composer
, or pick up on the exported custom wallet specified within NODE_CONFIG
if and only if executing within the same shell instance.
To specify a custom wallet within the API, without the use of a globally exported value, it must be included as an option passed to the connection:
const connectionOptions = {
wallet : {
type: 'composer-wallet-filesystem',
options : {
storePath :'/my/network/location'
}
}
};
adminConnection = new AdminConnection(connectionOptions);
clientConnection = new BusinessNetworkConnection(connectionOptions);
In the above, the wallet type may be that of a new file location, or a cloud based location.
API MemoryCardStore configuration
Previously to use the in MemoryCardStore, the code would have been written
cardStore = new MemoryCardStore();
const adminConnectionOptions = {
cardStore : cardStore
};
adminConnection = new AdminConnection(adminConnectionOptions);
// or more concisely
clientConnection = new BusinessNetworkConnection({cardStore});
This has now changed and Card stores must now be specified differently:
const connectionOptions = {
wallet : {
type: 'composer-wallet-inmemory'
}
};
adminConnection = new AdminConnection(connectionOptions);
clientConnection = new BusinessNetworkConnection(connectionOptions);
Cloud Wallets and Hyperledger Composer Rest Server
For convenience, the latest Hyperledger Composer Rest Server docker image will have all the cloud wallets available on the github repository for composer-tools preloaded into the image.