Hyperledger fabric-samples: what the repository actually gives you

What fabric-samples is for, and who it is not for

The repository exists so that a developer can reach a running Hyperledger Fabric network and a deployed chaincode without designing the network first. The README frames it as a way to "get started working with Hyperledger Fabric, explore important Fabric features, and learn how to build applications that can interact with blockchain networks using the Fabric SDKs." That is a teaching scope, and the directory listing matches it: test-network, test-network-k8s, test-network-nano-bash, a set of asset-transfer-* samples, token samples for ERC-20, ERC-721 and ERC-1155, two auction samples, off_chain_data, hardware-security-module and high-throughput.

The audience is therefore developers new to Fabric, and developers who already know Fabric but need a reference implementation of a specific capability. The asset transfer series is organized exactly that way. Basic covers writing a contract and calling it through an SDK. Ledger queries adds range queries and CouchDB indexes. Private data covers private data collections and the hash that proves a private write happened. State-based endorsement moves the endorsement policy from the chaincode level to the key level. Secured agreement combines implicit private data collections, state-based endorsement and organization-based ownership into a transfer that needs both buyer and seller consent.

It is not for someone who wants a production network. Nothing in the README describes hardening, certificate authority operations at scale, backup, or multi-region ordering. The Kubernetes sample is the closest thing to a deployment story, and the README describes it as a platform to "author and debug cloud ready Fabric Client applications on a development or CI workstation," which is a development framing, not an operations one.

The test network: two peers, one orderer, Docker Compose

The core mechanism is the test network in the test-network directory. The README states it "provides a Docker Compose based test network with two Organization peers and an ordering service node." That is the whole topology: two peer organizations plus a single ordering service node, brought up with Docker Compose on one machine. The README also says you can use it to "deploy and test your own Fabric chaincodes and applications," which is the intended workflow. You are not expected to modify the network definition to learn Fabric; you are expected to leave it alone and point your chaincode at it.

The Kubernetes variant, test-network-k8s, "builds upon the Compose network, constructing a Fabric network with peer, orderer, and CA infrastructure nodes running on Kubernetes." Note the addition of CA nodes. The Compose network does not describe certificate authority infrastructure in the README text, while the Kubernetes one explicitly names it, so if your interest is in how identities get issued in a cluster, that is the sample to read.

A third option exists that the README does not describe in prose but the directory listing shows: test-network-nano-bash. There is no README text for it in the repository README, so treat it as an unverified path and check its own files before relying on it.

The data flow across all of these is the same. A client application uses a Fabric SDK to submit a transaction proposal to endorsing peers, collects endorsements, and submits the endorsed transaction to the ordering service, which batches it into a block that peers then validate and commit. The samples differ in what the chaincode does at that first step and in which parts of the flow they expose to you.

Installing fabric-samples and running your first chaincode

The README does not contain install commands. It says to first install the Fabric prerequisites, then follow the Fabric documentation page titled Install the Fabric Samples, Binaries, and Docker Images. That page, per the README, downloads the Fabric Docker images and the CLI tool binaries and also clones the samples to your machine. So the entry point is the documentation site, not this repository.

The README does not print the installer command itself, so the honest sequence is: install the prerequisites, run the install as documented there, then confirm the result locally. After installation you should have a fabric-samples directory and the Fabric binaries available. Check the binaries first:

peer version

The output names the Fabric version your binaries were built for. Compare it against the branch you cloned, because the README states that this branch "contains samples for the latest Fabric release" and that release-2.2 and release-1.4 exist for older versions. A mismatch between binaries and samples is a common source of confusing errors.

Next, from the test-network directory, bring up the network. The test network tutorial linked from the README is the reference for the exact commands. The README does not print the network script invocations, so follow that tutorial rather than guessing at flags. What you should see when the network is up is containers for two peers and one orderer, and the script reporting the network as running.

Once the channel is created, deploy a chaincode from one of the asset transfer samples. The README lists Go, JavaScript, TypeScript and Java as smart contract languages for the Basic sample, and Go, TypeScript and Java for its applications. If you select a language the sample does not ship, the deploy step fails. Tear the network down when you are finished, otherwise the containers and channel artifacts persist and the next startup behaves unexpectedly.

Where fabric-samples stops being the right tool

The single ordering service node is the clearest boundary. A network with one orderer has no ordering service fault tolerance, and the README does not present the test network as anything other than a local development aid. If your goal is to evaluate Fabric's crash fault tolerant ordering under load, this repository does not give you the topology to do it. The high-throughput directory exists in the listing but the README text supplied here does not describe it, so its scope is unconfirmed.

Language coverage is uneven, and this bites people. The Basic sample supports Go, JavaScript, TypeScript and Java chaincodes, but the Secured agreement sample is Go only for the contract and TypeScript only for the application. State-based endorsement lists Java and TypeScript contracts with a JavaScript application. Attribute-based access control is Go only and, notably, has no application language at all in the table, meaning the README describes no client for it. If your team writes Java and you picked the secured agreement sample because it matches your business scenario, you are rewriting the contract.

The samples also assume a single machine with Docker. Nothing in the README addresses running the Compose network across hosts, and the Kubernetes path is framed around a development or CI workstation. Teams that need a multi-host development environment should read test-network-k8s closely before assuming it covers them.

Finally, the release history is thin. The two most recent releases listed are v2.0.0-beta from 2019-12-16 and v1.4.4 from 2019-11-15. The repository is not archived and the last push was on 2026-09-18, so work continues on the main branch, but the tagged release channel has not been the distribution mechanism for years. You consume this repository by cloning a branch, not by picking a release artifact.

How this differs from writing your own network definition

The alternative to using fabric-samples is generating your own network: writing the crypto material, the channel genesis block, the peer and orderer configuration, and the Docker or Kubernetes manifests yourself, typically with the Fabric binaries' cryptogen and configtxgen tools. That path gives you control over the number of orderers, the ordering service type, the MSP layout and the channel policies from the first commit.

The difference in approach is who owns the defaults. In fabric-samples the defaults are given to you and are deliberately minimal: two peer organizations, one orderer, a Compose file. In a self-built network you choose everything, and you will spend the first days reproducing what the test network already does before you reach anything the samples do not cover. For learning what a Fabric transaction actually is, the samples are faster. For a network whose topology you must defend in a design review, the samples are a starting reference and nothing more.

There is a middle path worth naming: use the test network to develop and debug the chaincode, then port that chaincode into a network definition you own. The chaincode itself is the portable artifact. The network around it is not.

Maintenance, branches and licence

The repository is not archived and the last push was on 2026-09-18, so the main branch is receiving changes. That does not make the tagged releases current: the newest listed release is v2.0.0-beta from 2019-12-16. Practically, this means your upgrade path is a git pull on a branch, and the branch you choose is a compatibility decision. The README states that this branch tracks the latest Fabric release and that release-2.2 and release-1.4 exist for older Fabric versions. Pulling main against release-2.2 binaries will not go well.

Upgrade cost is therefore mostly the cost of keeping three things aligned: the Fabric binaries, the Docker images, and the sample branch. The README's install page downloads images and binaries together, which helps, but nothing in the README describes a version pinning file you can commit. You will be tracking a moving branch unless you fork.

The code is Apache-2.0, and the README carries an SPDX header marking the documentation text as CC-BY-4.0. Apache-2.0 permits commercial use and modification and includes a patent grant. If you copy a sample chaincode into a product, you are taking on the obligation to retain the licence and attribution notices. This is a description of the licence terms, not legal advice; read LICENSE and your own counsel's guidance before shipping derived code.

Editorial conclusion

Adopt fabric-samples if you are learning Hyperledger Fabric or need a known-good network to develop a chaincode against, and start with asset-transfer-basic rather than a token or auction sample. Do not adopt it as a production topology: the test network is a Docker Compose file with two organization peers and one ordering service node, and the README describes it as something to run on your local machine. Before building anything on it, verify which branch matches your Fabric release, since the README states that this branch tracks the latest release and points to release-2.2 and release-1.4 for older ones, and confirm that the chaincode language you intend to write is listed for the sample you picked.

Frequently asked questions

Official sources

1. hyperledger/fabric-samples on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases