This guide focuses on setting up Hyperledger Fabric 2.2 LTS and verifying it quickly in a local environment. It addresses common beginner issues such as dependency installation, missing binaries, slow image downloads, and test network startup failures. Keywords: Hyperledger Fabric, Docker, chaincode deployment.
Technical specifications at a glance
| Parameter | Details |
|---|---|
| Core framework | Hyperledger Fabric 2.2.9 LTS |
| Operating system | Ubuntu 16.04 LTS, 64-bit |
| Development language | Go 1.18.7 |
| Container engine | Docker 20.10+ |
| Orchestration tool | Docker Compose 1.25+ |
| Protocol/model | Consortium blockchain, channels, chaincode |
| Sample repository | fabric-samples |
| Core dependencies | Git, cURL, Docker, Docker Compose, Golang |
| GitHub stars | Not provided in the source; refer to the official repository for live metrics |
This guide provides a reproducible path for setting up a local Fabric environment
The complexity of installing Hyperledger Fabric does not come from a single command. It comes from getting dependency versions, directory structure, permissions, PATH configuration, and download reliability all aligned at the same time. The official materials are complete, but the information is scattered.
This guide compresses the workflow into three stages: installing base dependencies, downloading Fabric binaries and images, and validating the environment with test-network. This structure is better suited for developers who want to reproduce the setup quickly.
Recommended environment baseline
Use Ubuntu 16.04 LTS or a compatible Ubuntu distribution whenever possible. The minimum memory requirement is 2 GB, but 3 GB or more is recommended. Allocate at least 30 GB of disk space. If you use Windows or macOS, you can install an Ubuntu virtual machine with VMware or VirtualBox.
# Check the OS and kernel version # Core prerequisite check
uname -a
lsb_release -a
free -h
df -hThese commands confirm whether the operating system version, memory, and disk capacity meet the requirements for running local Fabric experiments.
Base dependencies must be installed completely first
A local Fabric network depends on Git to fetch sample repositories, cURL or scripts to download resources, Docker to run node containers, Docker Compose to orchestrate services, and Go to support chaincode and part of the toolchain.
Among these components, Docker and Go are the most likely to fail because of version mismatches or permission issues, so verify them first.
Install Git, cURL, Docker, and Docker Compose
sudo apt update # Update the package index
sudo apt install -y git curl # Install source download and network tools
sudo apt install -y docker.io # Install the Docker engine
sudo apt install -y docker-compose # Install Docker Compose
sudo systemctl start docker # Start the Docker service
sudo systemctl enable docker # Enable Docker on startup
sudo usermod -a -G docker $USER # Add the current user to the docker groupThis step prepares the core container runtime infrastructure required by Fabric.
Install and configure Golang 1.18.7
Fabric 2.2.x requires a relatively recent Go version. The original material uses Go 1.18.7, which is both stable and practical.
cd ~ # Return to the user home directory
mkdir -p download && cd download # Create a download directory
wget https://golang.google.cn/dl/go1.18.7.linux-amd64.tar.gz # Download the Go package
sudo tar -zxvf go1.18.7.linux-amd64.tar.gz -C /usr/local/ # Extract it to the system directoryThese commands install the Go binary distribution. If extraction fails with an EOF error, the archive is usually incomplete.
sudo vim /etc/profileAppend the following lines to the end of the file:
export GOPATH=$HOME/go # Set the Go workspace
export GOROOT=/usr/local/go # Set the Go installation directory
export PATH=$GOROOT/bin:$PATH # Add Go to the system PATHThis configuration allows the system to call the go command directly and prepares the environment for later chaincode dependency downloads.
The official Fabric script can automatically download samples, binaries, and images
The official recommendation is to use bootstrap.sh to fetch fabric-samples, platform-specific binaries, configuration files, Fabric CA, and Docker images. In practice, this script serves as the main installation entry point.
Use bootstrap.sh to install Fabric 2.2.9
cd ~ && mkdir -p fabric && cd fabric # Create the Fabric working directory
vim bootstrap.sh # Create the script file and paste in the official script
chmod +x bootstrap.sh # Grant execute permission
sudo ./bootstrap.sh # Run the automated installation scriptThis script clones the sample repository, switches versions, downloads binaries, installs CA tooling, and pulls container images.
If your network connection is unstable, the script most often fails during Docker image downloads. In that case, rerun sudo ./bootstrap.sh. Successfully downloaded artifacts usually do not download again.
You must complete the PATH configuration after execution
export PATH=$HOME/fabric/fabric-samples/bin:$PATH # Add Fabric binaries to PATH
source /etc/profile # Reload environment variablesThis step directly determines whether commands such as peer and configtxgen can be found by network.sh.
The test-network is the shortest path to validating the environment
Installing Fabric does not mean the environment is usable. The most effective validation method is to run fabric-samples/test-network. It starts the Peer and Orderer services and allows you to continue with channel creation and chaincode deployment.
Start the test network and create a channel
cd ~/fabric/fabric-samples/test-network # Enter the test network directory
chmod 755 network.sh # Ensure the script is executable
./network.sh down # Clean up old containers and networks
./network.sh up # Start the base network
./network.sh createChannel # Create the default channel mychannelThese commands perform environment cleanup, node startup, and application channel creation. Together, they form the core connectivity validation flow.
Deploy sample chaincode for functional verification
./network.sh deployCC \
-ccn basic \
-ccp ../asset-transfer-basic/chaincode-go \
-ccl goThis command deploys the Go version of the asset-transfer-basic chaincode to the default mychannel channel and verifies that the chaincode lifecycle works correctly.
Common errors usually come from PATH, permissions, and network dependencies
The most typical error is Peer binary and configuration files not found. This does not mean the startup script is broken. It usually means the Fabric binary directory is not included in PATH, or the files in the bin directory do not have execute permission.
Troubleshoot binary and permission issues
export PATH=$HOME/fabric/fabric-samples/bin:$PATH # Add the Fabric command path
cd ~/fabric/fabric-samples/bin && ls # Check whether the binaries exist
sudo chmod 774 * # Add execute permissions in batch
cd ../test-network && ./network.sh up # Return to the test network and start it againThese recovery commands address the most common missing binary and insufficient permission issues.
Resolve slow Go dependency downloads
When chaincode deployment fails because Go module dependencies cannot be downloaded, switch to a Go proxy to improve success rates on constrained networks.
go env -w GO111MODULE=on # Enable Go Modules
go env -w GOPROXY=https://goproxy.cn,direct # Configure a regional proxy
go env -w GOPRIVATE=*.corp.example.com # Optional: direct access for private repositories
./network.sh down # Shut down and clean up the current network
./network.sh up createChannel # Restart the network and create the channelThis significantly reduces dependency download failures during the first chaincode deployment.
Manual installation is the fallback option when the automated script fails
If bootstrap.sh keeps failing for an extended period, you can manually download hyperledger-fabric-linux-amd64-2.2.0.tar.gz and hyperledger-fabric-ca-linux-amd64-1.4.7.tar.gz.
After extraction, copy the bin and config directories to the root of fabric-samples, and make sure the current user has permission to access ~/fabric/. If needed, run sudo chown -R username:username ~/fabric/.
The acceptance criteria for this workflow should be clearly observable
Success does not mean only that commands were executed. It means three conditions are true at the same time: Docker images have been pulled, test-network starts successfully, and chaincode can be deployed.
If you can see images such as hyperledger/fabric-peer, hyperledger/fabric-orderer, and hyperledger/fabric-tools, and ./network.sh up, createChannel, and deployCC all complete successfully in sequence, the environment is ready for local development.
FAQ
Why does ./network.sh up report that the Peer binary cannot be found?
Because fabric-samples/bin is not included in PATH, or the binary files do not have sufficient execute permission. First run export PATH=$HOME/fabric/fabric-samples/bin:$PATH, then verify that the bin directory exists and is executable.
Why does bootstrap.sh often fail during the download phase?
The root cause is usually an unstable network connection, especially while pulling Docker images and GitHub-hosted resources. Retry the script first. If necessary, run it during off-peak hours or manually download the binary archives.
Why does chaincode deployment stall while downloading dependencies?
This is usually caused by the Go module download path. For Go 1.13 and later, set GOPROXY=https://goproxy.cn,direct, then rerun down, up createChannel, and deployCC to complete deployment.
Core summary: This guide restructures the Hyperledger Fabric setup workflow and covers installing Git, cURL, Docker, Docker Compose, Golang, and Fabric 2.2 LTS on Ubuntu, along with automated deployment using bootstrap.sh, PATH configuration, test network startup, channel creation, chaincode deployment, and common troubleshooting steps.