This is a boilerplate application to get you up and running quickly with your own blockchain application. With this boilerplate you get an application that you can run locally as well as on IBM Bluemix. There is a simple Angular frontend application, a NodeJS backend application and of course a blockchain network, all running in containers. Locally, the boilerplate starts up a blockchain network using Docker containers; on Bluemix you can use the Blockchain service.
The boilerplate uses Hyperledger Fabric v0.6.1-preview and HFC 0.6.5.
It has been created and is maintained by the IBM CIC Benelux Blockchain team. Pull requests are more than welcome!
To have good support in your IDE it's advisable to also install NPM, TypeScript, TSLint and Golang.
git clone
your forkcd
into the main directory and run npm install
(or, if you don't have npm, ./install.sh
).This will pull the baseimage, peer and memberservice, download the Go dependencies of the chaincode and build your containers. It will take a while.
To get rid of missing module errors in your IDE, also run npm install
from the server
and client
directory. This is not mandatory to run the application.
To run the application, simply do docker-compose up
.
This will start the three tiers of our application in separate containers:
The app is running on http://localhost:4200/
. You can login with the user credentials you find in server/resources/testData.json
Both the frontend and the server use filewatchers. Any change in the source files will trigger the transpiler and restart that part of the application.
Every time you pull changes, update the package.json of the server or client or change anything that might affect deployment of chaincode: docker-compose build
.
When you end docker-compose, the containers still exist. They keep state:
So if you start the app again, you can use your old chaincode. If you want to clear, just run with docker-compose up --force-recreate
.
Currently if you change the chaincode you will have to recreate the containers. In the future we will add a filewatcher for the chaincode as well.
Notes:
blockchain/src/build-chaincode/vendor.yml
.blockchain/src/build-chaincode/vendor
directory npm run govend
from the project root docker-compose build
We support unittests for the server, client and chaincode. Especially for writing chaincode we recommend a test-driven approach to save time. You can find the commands to run the tests in the package.json in the root:
npm run test-go
(blockchain/src/build-chaincode/chaincode_test.go
contains mock functions for the chaincode stub)npm run test-server
(see the server/tests
directory)npm run test-client
(each component has its own test, courtesy of angular-cli)npm run test-e2e
(needs the application to be running, it hits the API endpoints for end to end testing)npm test
runs all the tests except for e2e.You can also run the server tests directly from the server directory with npm test
and npm run e2e
.
no rows in result set
: The memberservice remembers something outdated. Stop your app and run ./clean.sh
.name or token does not match
: The info in blockchain/data/keyValStore does not match with the connected memberservice. ./clean.sh
.Can't connect to docker daemon.
: sudo usermod -aG docker $(whoami)
, logout and login again.Error: /usr/src/app/node_modules/grpc/src/node/extension_binary/grpc_node.node: invalid ELF header
: The node_modules of the server were built outside of the container. Delete this directory and make a change in server/package.json
. Then do docker-compose build server
.HFC:
handshake failed
: is there a certificate.pem
in the blockchain/src/build-chaincode
dir?docker-compose build
The SDK needs to register and enroll an admin user and any other users you would like to add. When this takes place the SDK receives enrollment certificates (eCerts) for each user. You only get these certificates once. So if you would redeploy or restart your app on Bluemix and the SDK wants to register and enroll the users again this would fail. Our solution to this problem is to register and enroll the users from your local environment before you deploy. When the eCerts are received, you can then push the app to Bluemix, including the eCerts. So the app that runs on Bluemix does not have to register and enroll the users again, because the eCerts are already available.
Don't lose server/resources/keyValueStore-bluemix! or else you'll have to recreate the blockchain service on Bluemix.
The easiest way to deploy a chaincode is to do it from you local environment before you push the app to Bluemix. We made a script that deploys the chaincode and stores the chaincodeID in a file. After that you push the app to Bluemix (including the chaincodeID file), your app can interact with the chaincode.
Perform the following steps to run the application on Bluemix:
server/resources/credentials.json
. If you retrieve your Service Credentials from a new console instance of Bluemix then you will need to edit your credentials.json. Add "credentials": {
to line 2 and then add a closing }
to the final line. Your finished payload should be 233 lines. Dockerfile
.server/resources/keyValStore-bluemix
directory if it exists, it contains keys to the previously used service.npm run cf
. cd server && npm run deploy
(This can take a few minutes)Network
tab. Ensure that it is running on all four peers and that all the way at the end it says Up for x seconds/minutes
. The blocks with transactions for the deployment and the invocation of the testdata function should be visible on the Blockchain
tab.cf push
, still from within the container.For assistance with the cloud foundry cli, visit the cloud foundry repo.
After the app has been pushed to Bluemix, you can view the logs with:
cf logs [NAME_OF_THE_APP] --recent
Where NAME_OF_THE_APP is the app name you provided in the manifest.yml file.
Hyperledger project: https://www.hyperledger.org/
Official Hyperledger slack channel: https://hyperledgerproject.slack.com
IRC: #hyperledger on freenode.net
Wiki: https://wiki.hyperledger.org/
HFC: https://www.npmjs.com/package/hfc/
Bluemix https://console.ng.bluemix.net/docs/
IBM on blockchain: https://www.ibm.com/blockchain/what-is-blockchain.html