-
Notifications
You must be signed in to change notification settings - Fork 10
Setting up Hyperledger Fabric for Obsidian
(Updated Jul 18 2018)
Obsidian currently runs on Hyperledger Fabric version 1.1. It's possible these instructions will also work with version 1.2, but we haven't tested this.
Note: these instructions are primarily written for Linux, as we've set it up there twice.
Fabric is kind of extremely complicated to set up, especially if you want to run it with experimental features like supporting chaincode written in Java. If you find a way to simplify some of these instructions, please let us know, because these instructions are basically cargo-culted together in a way that usually works.
Ensure you have all the prerequisites for Hyperledger installed: cURL, Docker, Docker Compose, and Golang. Since Obsidian runs on the Java Fabric platform, you don't need Node or NPM, but you will need them if you want to run some of the Hyperledger examples. These instructions don't rely on the Docker containers provided by Fabric, either, but the Hyperledger compilation process will fail if you don't have Docker installed.
Next, download and install the Hyperledger Fabric Samples and the Platform-Specific Binaries. It's unclear if the fabric samples are strictly required, but they are good for testing purposes if you run into issues. (in particular, you can try following the beginning of these instructions to see if you can get the basic network setup to work.)
The platform-specific binaries should have ended up in a folder somewhere called bin/. Add this folder to your PATH variable. You should now be able to run the peer command and get a "usage" message.
If you don't get a "usage" message, and instead get a message unknown config type "" or something like that, try setting FABRIC_CFG_PATH to a path containing both core.yaml and an msp/ folder, as peer needs both of these in order to run. You can use find to find these files in your Hyperledger Fabric samples directory if need be, or you can try to generate them using the "Manually generate the artifacts" instructions.
As root, create a directory to store Hyperledger files in. Fabric expects this directory to exist, and will try to create it if it doesn't exist, but if you're not running it as root, it won't be able to, and will fail. So, run these two commands as root:
# mkdir /var/hyperledger
# chown <your username> /var/hyperledger
Now, since this directory exists and you're the owner of it, you don't need to run Fabric with sudo privileges.
(On other operating systems, Hyperledger will probably look for a different place to put its files. Not sure which directory this is.)
In order to run Java chaincode, you need to re-compile the platform-specific binaries manually using the experimental build flag. Run this command:
$ go get -u --tags nopkcs11 github.com/hyperledger/fabric/core/chaincode/shim
This will download the Fabric shim code for version 1.2, which doesn't actually include the Java chaincode shim, because it has been moved to its own repository. So, run these commands to get the 1.1 version code:
$ cd $GOPATH/src/github.com/hyperledger/fabric
$ git checkout release-1.1
Open the Makefile in this directory with your text editor of choice. Find the line that says EXPERIMENTAL ?= false and change it to EXPERIMENTAL ?= true. (The ?= just means "set the variable if it's not already set." Yes, we were all wondering that.)
Now, you're all ready to recompile in experimental mode. Run make and then sit back and relax, because it takes a while. Go get more coffee. When you come back, you might find that it has failed to run some unit tests because it's missing the behave library. This is fine. If it made it that far, you're good to go. (If not these unit tests, some other tests might have failed. There are a lot of tests. It's OK if they don't all pass; the program will still work fine.)
Now, you should have a directory called build/bin/, which contains the newly compiled versions of all the platform-specific binaries. If you change to this directory and run ./peer version, you should see a line that says Experimental features: true. If it says false, check that the Makefile really does set EXPERIMENTAL to true.
Now, copy all these new binaries over into the folder where you originally downloaded the platform-specific binaries, overwriting your current version of peer, etc. If you're worried, you can save the precompiled versions somewhere else, but you won't need them in the future. Now just running peer version should tell you that experimental features are enabled.
Now that you have a proper experimental version of peer, you're all set to run compiled Hyperledger Fabric chaincode. You can tell the Obsidian compiler to generate code for Hyperledger by passing it the --hyperledger command-line flag. This will compile some Java files and then run a Gradle build script which produces a JAR file located at build/chaincode.jar.
In order to simplify the multi-stage process of entering complicated commands to start Fabric, deploy chaincode, etc., we've created some shell scripts which handle a lot of the grunt work for you. These shell scripts are located in the buildscript/ directory.
In order to start Fabric and deploy one chaincode (for the first time), run this command in a separate terminal:
$ buildscript/startfabric.sh build/chaincode.jar clean
(replacing build/chaincode.jar by the path to your chaincode JAR, if you moved it.)
Note the clean option, which, when provided, deletes your entire /var/hyperledger/production directory and recreates it in order to reset the state of the blockchain. This is necessary because Hyperledger doesn't really support deleting chaincodes or channels, because of the nature of blockchains, but this makes it difficult to reset things.
Be on the lookout for stack traces, as the shell script doesn't handle errors in the process very well and will usually insist it succeeded, even when it didn't. (We can't just look at return codes, as many of the processes are supposed to keep running indefinitely, and also the some of them don't return very useful return codes.)
If you want to start a chaincode to pick up where it left off, you can leave off the clean option. This will cause some errors to print out during the 'create channel' and 'install chaincode' processes, as the channel has already been created and the chaincode has been installed. Using the script is still recommended, though, because the script handles parsing the output of peer to find the appropriate address to pass to the chaincode, among other things.
Once the chaincode is running, keep the process running (i.e. don't suspend the script with Ctrl-Z.) In a different terminal, you can use buildscript/instantiate.sh to call the constructor of the chaincode. In order to pass parameters to this, each individual parameter must be double-quoted (in order to interpolate it into JSON), and the whole parameter list must be single-quoted (to prevent the shell from eating the double quotes.) An instantiation with parameters therefore looks something like:
$ buildscript/instantiate.sh '"3","4"'
In order to instantiate without parameters, run instantiate.sh like so:
$ buildscript/instantiate.sh -
(Note the -.)
Once you've instantiated the chaincode, you can now run transactions! Use invoke.sh to run transactions on the current chaincode, passing it the transaction name and the parameters (quoted in the same silly way):
$ buildscript/invoke.sh setX '"4"'
Note: you can't invoke transactions on the chaincode until it has been instantiated.
That's it! I hope these instructions work. Every time we install Hyperledger on a new machine, we encounter new and exciting errors, so if you run into an issue not covered here, and solve it, feel free to add it to this wiki page.