Debut Infotech
Published in

Debut Infotech

The Expert’s Guide to Hyperledger Fabric v2.0 Migration

In our previous blog posts, we discussed briefly what Hyperledger Fabric v2.0 brings to the table and how it a perfect-fit for enterprise-grade production environments. Also, we gave you a detailed walkthrough on two of its most prominent features stated, “Decentralized Governance for Smart Contracts” and “External Chaincode Launcher”, making it easy for developers to understand the potential of Fabric 2.0 in a clear and practical way.

As promised, we’re back again this week with another featured topic surrounding Fabric 2.0, i.e. “Upgrading to Hyperledger Fabric version 2.o”. So, without wasting any more time, let’s get things rolling.

Just like any other release, Fabric v2.0 comes with a ton of upgrade considerations that need to be taken care of before you plunge into its migration. However, unlike other major releases, you don’t have to install the new version from scratch, which minimizes the risk of downtime. This certainly means that if you’re already using version 1.4 or higher, then you can directly upgrade to the latest version, i.e. v2.0 without any downtime.

If you’re a hardcore Fabric developer or someone familiar with the previous releases of Hyperledger Fabric, then you probably know that upgrading the nodes and channels to the latest version of Fabric, with minimal downtime & disruption, involves the following four steps:

  • Firstly, you need to backup the ledger and MSPs.
  • Once you’re done with that, start upgrading the orderer binaries in a rolling fashion to the latest Fabric version.
  • Next, just like orderer binaries, upgrade the peer binaries as well.
  • Then, at last, update the orderer system channel and any application channels to the latest capability levels, wherever available.

Note: While some releases have capabilities in certain groups, others may have few or even no capabilities at all. For deeper insights into capabilities, you can check the channel capabilities of Hyperledger Fabric.

In case you experience any issues while upgrading to Fabric v2.0, then you can glance through the official documentation of Hyperledger to make the whole process a breeze.

However, before you upgrade any processes, it’s always advisable to check out their tutorials first. Below we have summarized the necessary steps for you, which will save your time watching those time-consuming & dreary tutorials and help you get started with Fabric v2.0 migration on the right foot.

Upgrade your components: Upgrade your Fabric components to the latest version before updating the capabilities.

Update the capability level of a channel: You need to first update all your nodes to the latest version, i.e. v2.0 before you can update the capability level of your channel.

Enable the new chain code lifecycle: It is essential to add organization-specific endorsement policies centered around the new chain code lifecycle for Fabric version 2.0.

These are the steps you need to follow to migrate to Fabric v2.0, however, as mentioned above, there are certain upgrade considerations that you need to keep in mind to make this transition as smooth as possible.

Considerations for migrating to Fabric v2.0

  • Chaincode Lifecycle

Fabric 2.0 is integrated with the new chain code lifecycle that enables multiple organizations to decide on how a chain code will be operated before they can use it on a channel. To learn more about the new chain code lifecycle, check out this blog post.

It is recommended to update all the peers on a channel before enabling the Channel and Application capabilities that enable the new chaincode lifecycle.

Note: Although the Channel capability is not strictly required, it is ideal to update it right away.

Keep in mind that any peers that are not at v2.0 will automatically crash after enabling either of the above-mentioned capability. Moreover, any ordering nodes that are not at v2.0 will crash right after the Channel capability is enabled.

Once the Application capability is updated to v2.0 on a channel, it is necessary to use Fabric v2.0 lifecycle procedures to package, install, approve, and commit new chaincodes on a channel.

This was all about the chaincode lifecycle consideration. Now moving to the next consideration, i.e. Chaincode shim changes.

  • Chaincode shim changes (Go chaincode only)

Before making upgrades to the peers and channels, it’s always advised to vendor the shim in your Fabric v1.4 Go chaincode. By doing this, you will not have to make any additional changes to your chaincode.

Even if you don’t vendor the shim, the old Fabric v1.4 chaincode images will technically work after upgrading your Fabric network to v2.0, but you’d probably be at risk. In case your version 1.4 chaincode image gets deleted from your environment due to any reason, the next invoke on version 2.0 peer will try to rebuild the chaincode image and you will get an error right away stating “the shim cannot be found”.

At this point, you would have two possible options. Either to vendor the new Go chaincode shim using modules or to rebuild the chaincode images using peer environment variables.

  • Chaincode Logger (Go chaincode only)

No more support for user chaincodes to utilize the chaincode shim’s logger via NewLogger(). It has now become necessary for chaincodes that used the shim’s NewLogger to shift to their own preferred logging mechanism. For more information on chaincode logger, check out Hyperledger Fabric’s Logging Control.

  • Peer databases upgrade

You need to rebuild the databases of all peers (state database, history database, and other databases) using the Fabric v2.0 format. To trigger the rebuild, the databases need to be dropped before the peer is started.

For detailed information about how to upgrade peers, you can glance through the official documentation of Hyperledger Fabric on upgrading components. While upgrading your peers, you will need to pass a peer node upgrade-dbs command to drop the databases of the peer.

To launch the peer, use the following command instead of using the docker run command:

docker run -d -v /opt/backup/$PEER_CONTAINER/:/var/hyperledger/production/ \-v /opt/msp/:/etc/hyperledger/fabric/msp/ \--env-file ./env<name of node>.list \--name $PEER_CONTAINER \hyperledger/fabric-peer:2.0 peer node upgrade-dbs

Using this command will drop the databases of the peer. Now, issue this command to start the peer using the 2.0 tag, as illustrated below:

docker run -d -v /opt/backup/$PEER_CONTAINER/:/var/hyperledger/production/ \-v /opt/msp/:/etc/hyperledger/fabric/msp/ \--env-file ./env<name of node>.list \--name $PEER_CONTAINER \hyperledger/fabric-peer:2.0 peer node start

Since database rebuilding can be a lengthy and time-consuming process (it might take several hours, depending upon the size of databases), it is necessary to monitor the peer logs to check the status of the rebuild.

After every 1000th block, the following message will be directed on the screen which indicates that the rebuild is ongoing.

[lockbasedtxmgr] CommitLostBlock -> INFO 041 Recommitting block [1000] to state database

In case the database is not dropped (as part of the upgrade process), the peer would return an error message conveying that its databases are in the old format and must be dropped using the peer node upgrade-dbs command above. In that case, the node will be restarted.

  • Capabilities

As one could expect from a typical 2.0 release, Fabric v2.0 comes with a plethora of new and exciting capabilities, which include:

Application V2_0: empowers the new chaincode lifecycle. You can read more about it here.

Channel V2_0: although this capability has no changes, it is used to maintain consistency with the application and orderer capability levels.

Orderer V2_0: transforms the way channel creation transactions are validated.

As with any update related to the capability levels, it is important to upgrade your peer binaries before updating the Application and Channel capabilities. Also, don’t forget to upgrade your orderer binaries before updating the Orderer and Channel capabilities.

  • Define ordering node endpoint per org

In Fabric v1.4.2 or higher, it was recommended to define orderer endpoints in both the system and application channels, which could be done by replacing the global OrdererAddresses section with a new stanza named OrdererEndpoints within the channel configuration of an organization.

In case your channel configuration does not yet include OrdererEndpoints per org, it would be necessary for you to perform a channel configuration update in order to add them to the config.

Now that you’re familiar with Fabric v2.0 migration considerations, as a network/node administrator, you need to get a better view of the process for upgrading components.

Note: The term “upgrade” in Hyperledger Fabric refers to the changing version of a component (for example, going from one version of a binary to the next version). On the other hand, the term “update” refers to the change in configuration rather than version (for example, updating a channel configuration or a deployment script).

Upgrade ordering nodes

It is recommended to upgrade orderer containers in a rolling fashion (one at a time). At a high level, below are the steps that you need to follow to upgrade your ordering nodes:

  • First, you need to stop the ordering node.
  • Then, it is advised to back up the ordering node’s ledger and MSP.
  • Remove the ordering node container.
  • Last but not the least, launch a new ordering node container using the relevant image tag.

Note: Repeat these steps for each node in your ordering service until the entire ordering service is upgraded.

Set command environment variables

Before attempting to upgrade your ordering nodes, you need to export the following environment variables:

  • ORDERER_CONTAINER: Represents the name of your ordering node container. You will need to export this variable for each node when upgrading it.
  • LEDGERS_BACKUP: Signifies the place in your local filesystem where you want to store the ledger being backed up.
  • IMAGE_TAG: Represents the Fabric version you are upgrading to. For example, Fabric v2.0.

Upgrade containers

Kickstart the upgrade process by bringing down the orderer:


Once the orderer is down, back up its ledger and MSP:

docker cp ORDERER_CONTAINER:/var/hyperledger/production/orderer/ ./$LEDGERS_BACKUP/$ORDERER_CONTAINER

Then, remove the ordering node container itself (since we will be giving our new container the same name as our old one):


Once the above-mentioned steps are taken care of, you can launch the new ordering node container by issuing the following:

docker run -d -v /opt/backup/$ORDERER_CONTAINER/:/var/hyperledger/production/orderer/ \-v /opt/msp/:/etc/hyperledger/fabric/msp/ \— env-file ./env<name of node>.list \— name $ORDERER_CONTAINER \hyperledger/fabric-orderer:$IMAGE_TAG orderer

Once all the ordering nodes have come up, you can move on to upgrading your peers.

Upgrade the peers

Just like the ordering nodes, peers should be upgraded in a rolling fashion (one at a time). Below mentioned are the steps you need to follow to upgrade the peers:

  • Stop the peer.
  • Back up the peer’s ledger and MSP.
  • Remove chaincode containers and images.
  • Remove the peer container.
  • Launch a new peer container using the relevant image tag.

Upgrade your CAs

It is advised to upgrade Fabric CA before upgrading the Fabric CA client. However, prior to upgrade, it is recommended to take a backup of the current database. Here’s how you can do that:

  • If you’re using sqlite3, then backup the current database file, which will be named fabric-ca-server.db by default.
  • In case you’re using other databases, use the appropriate backup/replication mechanism.

To upgrade a single instance of Fabric CA server, below are the steps that you need to follow:

1. Stop the fabric-ca-server process.

2. Make sure the current database is backed up.

3. Replace previous fabric-ca-server binary with the upgraded version.

4. Launch the fabric-ca-server process.

5. Verify whether the fabric-ca-server process is available with the following command where <host> is the hostname on which the server was started:

fabric-ca-client getcainfo -u http://<host>:7054

For detailed insights into how to upgrade your Fabric CA server, browse through the official CA documentation shared by Hyperledger Fabric.

Upgrade Node SDK clients

Before getting started with upgrading your Node SDK clients, it is recommended to first upgrade Hyperledger Fabric and Fabric CA. Both Fabric and Fabric CA are tested for backward compatibility with older SDK clients.

Use NPM to upgrade any Node.js client by executing the following commands in the root directory of your application:

npm install fabric-client@latestnpm install fabric-ca-client@latest

Using these commands, you can install the new version of both the Fabric client and Fabric-CA client and write the new versions to package.json.

Upgrade CouchDB

As a node/network administrator, if you’re using CouchDB as state database, it is recommended to upgrade the peer’s CouchDB at the same time the peer is being upgraded.

In order to upgrade CouchDB, follow the below-mentioned steps:

  • First, you need to stop CouchDB.
  • Then, backup CouchDB data directory.
  • Install the latest CouchDB binaries or update deployment scripts to use a new Docker image.
  • Last but not the least, restart CouchDB.

For detailed insights into upgrading Fabric components, visit

This was all about Hyperledger Fabric v2.0 migration. If you have any questions or need further assistance on upgrading to Fabric v2.0, then we’ve got you covered! Get in touch with one of our Blockchain adepts by dropping a line at or joining our Rocketchat channel.

For your knowledge, we’ve built an advanced Hyperledger Fabric Enterprise Network Management Solution integrated with Fabric v2.0 that allows a consortium of organizations to securely deploy a Blockchain network on their preferred cloud vCPUs, be it AWS, Microsoft Azure, Google Cloud, Digital Ocean, or any other cloud environment. For deeper insights into our solution, visit us.

Leave your thoughts about the post in the comments section below.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store