Skip to content

Instantly share code, notes, and snippets.

@nguyer

nguyer/firefly_dev_workshop.md

Last active May 24, 2022 23:11
Show Gist options
  • Star 3 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save nguyer/62cedff84e5fa5a5e313d060690e5bba to your computer and use it in GitHub Desktop.
Save nguyer/62cedff84e5fa5a5e313d060690e5bba to your computer and use it in GitHub Desktop.
Download ZIP
FireFly Developer Workshop
Raw
firefly_dev_workshop.md

FireFly Developer Workshop

This workshop will guide developers in setting up FireFly on their machine as well as a complete dev environment to be able to contribute code back to the FireFly project.

Workshop Goals

By the end of this workshop you will have:

  • A working developer environment capable of:
    • Building apps that run on FireFly
    • Making changes and contributions to the FireFly core itself
  • Sample apps running on your local machine
  • A working understanding of the components that make up a FireFly stack

Prerequisites

Please make sure you have the following software installed on your computer before the workshop. This will save time during the workshop and will help us make the best use of the time.

NOTE: For Linux users, it is recommended that you add your user to the docker group so that you do not have to run ff (the FireFly command line interface) or docker as root or with sudo. For more information about Docker permissions on Linux, please see Docker's documentation on the topic.

Make sure Go binaries are on your PATH

It's important that Go binaries are available on your PATH. You can verify that things are set up correctly by running this command in a terminal:

$ go version

You should see the following (your exact version and binary may differ) printed in your terminal if everything is set up correctly:

go version go1.16.3 darwin/amd64

If you do not see the correct output here, you need to add the go/bin directory to your PATH. There are several ways to do this, and they vary based on your operating system. Please see details for how to setup Go binaries on your PATH for your operating system here: https://golang.org/doc/install

Make sure GOPATH is on your PATH

When you run certain Go commands to install binaries or dependencies, they will be installed in your GOPATH. You'll want to make sure this directory is also on your PATH and it is usually not set up by default. Edit ~/.bashrc or ~/.zshrc (depending on which shell you're using) and make sure it contains the following lines near the bottom:

export GOPATH=$HOME/go
export GOROOT="/usr/local/opt/go/libexec"
export PATH="$PATH:${GOPATH}/bin:${GOROOT}/bin"

If you've completed this guide up to this point, you're ready for the workshop. Great job! We'll go through the rest of the steps together during the workshop.

Install the FireFly CLI

The FireFly CLI is a tool that will help us run FireFly and all of its dependencies locally. This is useful if you want to build an app that uses FireFly, and it's also useful if you want to contribute back to FireFly itself.

The FireFly CLI uses docker-compose to manage all the of services on which FireFly depends. It also takes care of a bunch of orchestration tasks such as deploying smart contracts and registering identities.

$ go install github.com/hyperledger-labs/firefly-cli/ff@latest

To verify that the CLI has been installed correctly, just run the ff command, which should print out information about running the CLI.

$ ff
    _______           ________
   / ____(_)_______  / ____/ /_  __
  / /_  / / ___/ _ \/ /_  / / / / /
 / __/ / / /  /  __/ __/ / / /_/ /
/_/   /_/_/   \___/_/   /_/\__, /
                          /____/

FireFly CLI is a developer tool used to manage local development stacks

This tool automates creation of stacks with many infrastructure components which
would otherwise be a time consuming manual task. It also wraps docker compose
commands to manage the lifecycle of stacks.

To get started run: ff init

Usage:
  ff [command]

Available Commands:
  help        Help about any command
  info        Get info about a stack
  init        Create a new FireFly local dev stack
  list        list stacks
  logs        View log output from a stack
  ls          list stacks
  remove      Completely remove a stack
  reset       Clear all data in a stack
  start       Start a stack
  stop        Stop a stack
  upgrade     Upgrade a stack

Flags:
      --ansi string   control when to print ANSI control characters ("never"|"always"|"auto") (default "auto") (default "auto")
  -h, --help          help for ff
  -v, --verbose       verbose log output

Use "ff [command] --help" for more information about a command.

Create a simple stack for running sample apps

Now that you have the CLI installed, we will start off by creating the most simple stack with all the default settings and just 2 members. Just run ff init, and fill in the interactive prompts from the CLI.

$ ff init
initializing new FireFly stack...
stack name: simple
You selected simple
number of members: 2
Stack 'simple' created!
To start your new stack run:

ff start simple

Your docker compose file for this stack can be found at: ~/.firefly/stacks/simple/docker-compose.yml

You can see the path to the generated Docker Compose file, as well as the command to start the stack.

NOTE: From this point forward, we will need the docker daemon running on your machine. If some of these commands cause errors, please double check that docker is running.

Start the FireFly stack

To start the stack, simply run: ff start simple (assuming you named your stack simple like the example above).

This will take a bit of time, but when it's done you should see some output like this:

$ ff start simple
reading stack config... done
this will take a few seconds longer since this is the first time you're running this stack...
done

Web UI for member '0': http://127.0.0.1:5000/ui
Web UI for member '1': http://127.0.0.1:5001/ui

To see logs for your stack run:

ff logs simple

Let's take a look at the UI for the first member by navigating to http://127.0.0.1:5000/ui in a browser. You should see a window like this:

FireFly Explorer

If you want to see the Swagger document for the API, you can also navigate to http://127.0.0.1:5000/api

FireFly Swagger

NOTE: There is a Postman collection available here that is set up to run some several of these endpoints against a local stack setup with the CLI

Run a sample app against the stack

Now that we have a really simple stack running, lets run a sample app against it. The samples are examples of how to use the FireFly API to perform transactions. You can look at their source code to get an idea of how to use the API and WebSocket event interfaces to learn how to build your own app.

To get the FireFly sample apps, clone the GitHub repo:

$ git clone git@github.com:hyperledger-labs/firefly-samples.git

There are two samples in the repo right now. One is a very simple command line app that just runs, sends a message, receives the message on the other member's node, and then exists. The other app is a slightly more full featured app with simple backend API, and a simple web UI. To start with, let's run the simple command line app.

$ cd firefly-samples/private-data-transfer-cli
$ npm install
$ npm start

> private-data-transfer-cli@1.0.0 start firefly-samples/private-data-transfer-cli
> ts-node src/index.ts

Broadcasting data values from firefly1: Hello,World
Received data value on firefly2: Hello,World

You can see from the log output that one node sent a message with two data items Hello and World, and the other node received that message. This is great. This means our stack is working. If we go back to the UI now, we should see some messages in the Explorer.

FireFly Explorer Messages

At this point, we have a working FireFly stack and we've been able to run some messages through the system. You now have everything you need to build an app that uses FireFly. The next sections of this guide will help you get set up to do development on the FireFly Core itself.

Set up the FireFly Core repo

First, we need to clone the main FireFly repo:

$ git clone git@github.com:hyperledger-labs/firefly.git && cd firefly

And run the Makefile to run tests, and compile the app

$ make

If you want to install the binary on your path (assuming your Go Home is already on your path), from inside the project directory you can simply run:

$ go install

At this time, let's stop the currently running simple stack by running:

$ ff stop simple

NOTE: You can have many FireFly stacks on your machine, each with their own config and data, but you can only run one at a time right now. If you tried to run multiple, their ports would collide at the moment.

Now that you have FireFly itself installed, it’s time to create a development stack. This time around we need to set up the stack slightly differently from our very simple setup above.

Essentially what we are going to do is have docker-compose run everything in the FireFly network except one FireFly core process. We’ll run this FireFly core process on our host machine, and configure it to connect to the rest of the microservices running in docker-compose. This means we could launch FireFly from Visual Studio Code or some other IDE and use a debugger to see what’s going on inside FireFly as it’s running.

To do this, we’re going to add --external 1 to the end of our command to create the new stack:

$ ff init --external 1
initializing new FireFly stack...
stack name: dev
You selected dev
number of members: 2
Stack 'dev' created!
To start your new stack run:

ff start dev

Your docker compose file for this stack can be found at: ~/.firefly/stacks/dev/docker-compose.yml

This tells the CLI that we want to manage one of the FireFly core processes outside the docker-compose stack. For convenience, the CLI will still generate a config file for this process though. At a certain point in the startup process, the CLI will pause and wait for up to two minutes for you to start the other FireFly node. It will also print out the command line which can be copied and pasted into another terminal window to run FireFly.

NOTE: The first time you run FireFly with a fresh database, it will need a directory of database migrations to apply to the empty database. If you run FireFly from the firefly project directory you cloned from GitHub, it will automatically find these and apply them. If you run it from somewhere else, you will have to point FireFly to the migrations on your own.

$ ff start dev
reading stack config... done
this will take a few seconds longer since this is the first time you're running this stack...
⡿ please start your firefly core with the config file for this stack: firefly -f ~/.firefly/stacks/dev/configs/firefly_core_0.yml  ...

At this point the CLI will pause its startup sequence and wait for you to launch a FireFly Core process on your host machine. It will also print the command you need, including the path to the config file you should use when starting the process.

You can also use the default run configuration provided in the FireFly repo to run FireFly in debug mode inside Visual Studio Code. This will let you set breakpoints and step through your code as you are working on changes.

NOTE: The CLI will wait up to 2 minutes (120 seconds) for you to launch the external FireFly Core process. If it is not running after that amount of time, an error will be thrown and the CLI will roll back the stack.

References

Resources

Documentation

FireFly Repositories

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment