Skip to main content

FireFly Stack Setup

This guide walks you through creating and managing a FireFly stack for the Fraktal project. A FireFly stack provides the orchestration layer for your Hyperledger Fabric blockchain network.

Prerequisites

Before proceeding, ensure you have completed the Chaincode Development Setup guide and have all required dependencies installed.

Creating Your FireFly Stack​

Initialize the Stack​

Create a new FireFly stack named 'dev' using the following command:

ff init fabric --prompt-names dev
macOS Users

The above command will not work on macOS due to port conflicts with some ports used by FireFly. Instead, use:

ff init fabric --prompt-names dev -p 8000

This starts the ports at 8000 to avoid conflicts with macOS system services.

Configure Organizations​

The initialization command will prompt you to configure your network organizations. You'll need to provide:

  1. Number of Organizations - How many organizations will participate in the network
  2. Organization Names - Unique identifiers for each organization
  3. Node Names - Names for each organization's nodes

Example Configuration​

For this documentation, we'll use the following setup:

SettingValue
Number of Organizations2
Organization 1 Nameorg1
Organization 1 Node Nameorg1_node_0
Organization 2 Nameorg2
Organization 2 Node Nameorg2_node_0
Customization

Choose the number and names of organizations based on your project requirements. You can create as many organizations as needed for your use case.

Starting the Stack​

Once initialization is complete, start the stack:

ff start dev

What Happens During Startup​

The startup process will:

  • Download necessary Docker images (first run only)
  • Configure the Fabric network components
  • Start all containers and services
  • Set up the FireFly orchestration layer
First Run

The first time you run this command, it may take several minutes as Docker downloads the required images. Subsequent starts will be much faster.

Verify Startup​

When the startup completes successfully, you should see output similar to:

Web UI for member '0': http://127.0.0.1:5000/ui
Swagger API UI for member '0': http://127.0.0.1:5000/api
Sandbox UI for member '0': http://127.0.0.1:5108

Web UI for member '1': http://127.0.0.1:5001/ui
Swagger API UI for member '1': http://127.0.0.1:5001/api
Sandbox UI for member '1': http://127.0.0.1:5208

To see logs for your stack run:
  ff logs dev

Access Your Stack​

You now have access to several interfaces for each organization:

Organization 1 (member '0'):

Organization 2 (member '1'):

Testing the Setup

Open the Web UI in your browser to explore the FireFly interface and verify everything is running correctly.

Managing Your Stack​

View Logs​

Monitor your stack's activity by viewing the logs:

ff logs dev

This command displays real-time logs from all containers in your stack. Press Ctrl+C to exit the log view.

Stop the Stack​

To stop all stack services without removing data:

ff stop dev

This command:

  • Stops all running containers
  • Preserves all data and configuration
  • Allows you to restart the stack later with ff start dev

Remove the Stack​

To completely remove the stack and all associated data:

# First, stop the stack
ff stop dev

# Then, remove it completely
ff remove dev
Data Loss Warning

The ff remove command permanently deletes all stack data, including:

  • Blockchain ledger data
  • Container configurations
  • Network settings

Only use this command when you're sure you want to start fresh.

Common FireFly CLI Commands​

Here are some useful commands for managing your FireFly stack:

CommandDescription
ff init fabric --prompt-names <name>Initialize a new Fabric stack
ff start <stack-name>Start a stopped stack
ff stop <stack-name>Stop a running stack
ff remove <stack-name>Remove a stack completely
ff logs <stack-name>View stack logs
ff info <stack-name>Display stack information
ff accounts list <stack-name>List blockchain accounts

For a complete list of available commands, refer to the FireFly CLI Documentation.

Troubleshooting​

Port Conflicts

Problem: Error about ports already in use

Solution:

# Check what's using the port (example for port 5000)
sudo lsof -i :5000

# Option 1: Stop the conflicting service
# Option 2: Use a different port base
ff init fabric --prompt-names dev -p 8000
Docker Issues

Problem: Docker-related errors during stack startup

Solution:

# Check Docker is running
docker ps

# Restart Docker service
sudo systemctl restart docker

# Clean up old containers
docker system prune -a
Stack Won't Start

Problem: Stack fails to start or hangs

Solution:

# Stop any running stack
ff stop dev

# Remove and recreate
ff remove dev
ff init fabric --prompt-names dev
ff start dev

# Check logs for specific errors
ff logs dev

Next Steps​

🎉 Your FireFly stack is now running! You're ready to deploy and interact with chaincode.

Continue to: Chaincode Deployment Guide

In the next guide, you'll learn how to:

  • Package your chaincode
  • Deploy it to the Fabric network
  • Invoke chaincode functions
  • Query the blockchain ledger

Additional Resources​