Using the IBM Blockchain images

Running a different version of IBM Blockchain Platform? Switch to version 2.1.3, 2.5, 2.5.1, 2.5.2.

Deprecation note: The option to use only IBM Blockchain images without the console is deprecated, along with all of the content on this page. Starting to use IBM Blockchain images without the console is no longer an option, as IBM Blockchain Platform software is no longer marketed and its end of support has been announced for April 30, 2023.

For experienced Hyperledger Fabric customers, the IBM® Blockchain Platform provides images for peer, CA, ordering service, and smart contract containers that are signed and supported by IBM. These images are the commercial distribution of Hyperledger Fabric v1.4.x and v2.x.

A key benefit of using these images over the open source community version is that IBM scans the open source code for security vulnerabilities daily as well as keeps the images up to date with operating system and vulnerability patches. Additionally, IBM provides 24x7x365 support with SLAs appropriate for production environments. The images are based on Red Hat Universal Base Image (UBI) and the blockchain components are enabled for HSM support.

IBM Blockchain Platform images can be purchased through an entitlement to the IBM Blockchain Platform 2.5.3. The images are bundled with support from IBM. While it is possible to configure mixed networks that include components (CAs, peers, and ordering nodes) from the IBM Blockchain Platform and Hyperledger Fabric community version, IBM support is limited to IBM Blockchain components. IBM does not support blockchain components that are deployed using the open source Hyperledger Fabric Docker images.

Supported Platforms

The IBM Blockchain images must be deployed using a container environment on x86_64 or s390x hardware. Refer to the list of Supported Platforms.

Although you can deploy the IBM Blockchain images on Mac OS for testing purposes, the permissions on Mac OS might prevent you from instantiating a smart contract.

Supported Fabric versions

The IBM Blockchain Docker images are based on Hyperledger Fabric v1.4.12 and v2.2.5. You can use this documentation to install and deploy the latest version of Fabric used by the IBM Blockchain Platform 2.5.3.

See the My Support page for details on what is supported.

Considerations and limitations

The images do not include the IBM Blockchain Platform console or operator. This offering is meant for experienced Fabric users with existing deployments. If you are still exploring Hyperledger Fabric, you can get started with IBM Blockchain Platform for IBM Cloud.

IBM Blockchain provides support for Hyperledger Fabric only if you purchase IBM Blockchain 2.5.3 and deploy the commercial distribution of Hyperledger Fabric images that comes with it. You cannot purchase support for the Hyperledger Fabric Docker images that are provided by the Hyperledger community.
IBM Blockchain does not support images that have been altered.
You cannot use the IBM Blockchain Platform console to deploy or operate these images. But, if you download the image for the gRPC web proxy and connect the proxy to node that you deploy, you can import the node into an existing IBM Blockchain Platform console. After you import a node into the console, you can operate that node alongside nodes that were deployed by using the IBM Blockchain Platform.

License and pricing

IBM Blockchain Platform images can be purchased through an entitlement to the IBM Blockchain Platform 2.5.3. After you purchase the platform, you can access the My IBM dashboard to obtain your entitlement key. You can then use the entitlement key to download the images from the IBM Entitlement Registry.

For more information on the pricing of the images, to the Pricing topic.

Get your entitlement key

When you purchase the IBM Blockchain Platform from PPA, you receive an entitlement key for the software is associated with your MyIBM account. You need to access and save this key to deploy the platform.

Log in to MyIBM Container Software Library with the IBMid and password that are associated with the entitled software.
In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard.

Downloading the IBM Blockchain Platform images

The platform recommends that you use the skopeo utility to download and copy your images to your local container registry. skopeo is a tool for moving container images between different types of container storages. In order to download the platform images and copy them to your container registry behind a firewall, you first need to install skopeo.

Before attempting these instructions, you need to have your IBM Blockchain Platform entitlement key and container registry user id and password available. After you purchase the IBM Blockchain Platform, you can access the My IBM dashboard to obtain your entitlement key for the offering. You can then use this key to access the IBM Blockchain Platform images.

Run the following set of commands to download the images and push them to your registry.

Replace

<ENTITLEMENT_KEY> with your entitlement key.
<LOCAL_REGISTRY_USER> with the userid with access to your container registry.
<LOCAL_REGISTRY_PASSWORD> with the password to your container registry.
amd64 - with s390x if you are installing on LinuxONE.

The following commands only work with a Docker container registry. Depending on the level of permissions required for the target location for the images, you might need to prefix each command with sudo.

skopeo copy docker://cp.icr.io/cp/ibp-operator:2.5.3-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-operator:2.5.3-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-init:2.5.3-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-init:2.5.3-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-console:2.5.3-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-console:2.5.3-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-grpcweb:2.5.3-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-grpcweb:2.5.3-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-deployer:2.5.3-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-deployer:2.5.3-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-fluentd:2.5.3-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-fluentd:2.5.3-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-couchdb:3.2.2-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-couchdb:3.2.2-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-peer:1.4.12-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-peer:1.4.12-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-orderer:1.4.12-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-orderer:1.4.12-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-ca:1.5.5-20230228 docker://<LOCAL_REGISTRY>/ibp-ca:1.5.5-20230228 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-dind:1.4.12-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-dind:1.4.12-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-utilities:1.4.12-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-utilities:1.4.12-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-peer:2.2.10-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-peer:2.2.10-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-orderer:2.2.10-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-orderer:2.2.10-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-chaincode-launcher:2.2.10-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-chaincode-launcher:2.2.10-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-utilities:2.2.10-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-utilities:2.2.10-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-ccenv:2.2.10-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-ccenv:2.2.10-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-goenv:2.2.10-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-goenv:2.2.10-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-nodeenv:2.2.10-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-nodeenv:2.2.10-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-javaenv:2.2.10-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-javaenv:2.2.10-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-peer:2.4.8-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-peer:2.4.8-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-orderer:2.4.8-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-orderer:2.4.8-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-chaincode-launcher:2.4.8-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-chaincode-launcher:2.4.8-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-utilities:2.4.8-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-utilities:2.4.8-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-ccenv:2.4.8-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-ccenv:2.4.8-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-goenv:2.4.8-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-goenv:2.4.8-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-nodeenv:2.4.8-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-nodeenv:2.4.8-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-javaenv:2.4.8-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-javaenv:2.4.8-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-crdwebhook:2.5.3-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-crdwebhook:2.5.3-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-ccenv:1.4.12-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-ccenv:1.4.12-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-goenv:1.4.12-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-goenv:1.4.12-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-nodeenv:1.4.12-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-nodeenv:1.4.12-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-javaenv:1.4.12-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-javaenv:1.4.12-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-enroller:2.5.3-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-enroller:2.5.3-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all
skopeo copy docker://cp.icr.io/cp/ibp-mustgather:2.5.3-20230228-amd64 docker://<LOCAL_REGISTRY>/ibp-mustgather:2.5.3-20230228-amd64 -q --src-creds cp:<ENTITLEMENT_KEY> --dest-creds <LOCAL_REGISTRY_USER>:<LOCAL_REGISTRY_PASSWORD> --all

Getting started

To deploy and operate the IBM Blockchain images, you can download the open source tools that are provided by the Hyperledger community. Follow the steps to Install the prerequisites and Download the Fabric Samples, Binaries, and configuration files in the Hyperledger Fabric documentation. These steps might download the open source Fabric images as well.

After you download the Fabric samples and binaries, you can find the configuration files and binaries that you need to set up a network in the fabric-samples\config and fabric-samples\bin folders. You can also find example artifacts and scripts for how to set up a network by using Docker Compose in the fabric-samples\first-network directory. You learn more about these artifacts and the steps that are involved by reading the accompanying Build Your First Network tutorial.

If you are using the open source configuration files, you need to make the following changes to deploy the IBM Blockchain images:

For each component, you need to alter the image field to use the IBM Blockchain image instead of the open source image.
Add the LICENSE field to accept the IBM license:
```
LICENSE=accept
```
If you are deploying a peer node, you need to use the core chaincode variables to instruct the peer to build chaincode using the IBM Blockchain certified images. For example, if you are using Go chaincode, you need to set the following variables:
```
CORE_CHAINCODE_NODE_RUNTIME=cp.icr.io/cp/ibp-nodeenv:1.4.12-20230228-amd64
CORE_CHAINCODE_GOLANG_DYNAMICLINK=true
```
You need to mount the configuration files, core.yaml or orderer.yaml, inside the node container. You also need to set the FABRIC_CFG_PATH environment variable to the path where you mounted the configuration files.

If you are deploying a peer node, you need to comment out or remove the PKCS11 section of the file unless you are using an HSM. The section of core.yaml that needs to be removed is below:
```
Settings for the PKCS#11 crypto provider (i.e. when DEFAULT: PKCS11)
PKCS11:
    # Location of the PKCS11 module library
    Library:
    # Token Label
    Label:
    # User PIN
    Pin:
    Hash:
    Security:
    FileKeyStore:
      KeyStore:
```
For security reasons, the IBM Blockchain images require a different level of permission to access data than the open source images. You need to change the access of the folder that you mount to store your organization MSP and TLS certificates and the folder that is mounted to store your ledger data. You can use the following command to change access to the folders before they are mounted inside the container:
```
chmod -R 777 <folder_name>
```

In addition to using the Fabric tools, you can also use the tools that are provided in the ibp-utilities image to operate your network. The utilities image includes the configtxlator, cryptogen, configtxgen binaries.

Configuring the gRPC web proxy (optional)

If you want to manage your nodes using the IBM Blockchain Platform console, you can deploy an instance of the gRPC web proxy and then connect it to a node that you deployed with the IBM Blockchain images. You can then import the node into a console that was deployed by using the IBM Blockchain Platform 2.5.3 or IBM Blockchain Platform for IBM Cloud. You need to deploy a separate web proxy for each node.

To deploy the proxy, you need to set the following environment variables inside the container.

LICENSE=accept
BACKEND_ADDRESS=<NODE_ENDPOINT_URL>
EXTERNAL_ADDRESS=<PROXY_ENDPOINT_URL>
SERVER_TLS_CERT_FILE=<TLS_CERTIFICATE>
SERVER_TLS_KEY_FILE=<TLS_KEY>
SERVER_TLS_CLIENT_CA_FILES=<ROOT_TLS_CERTIFICATE>
SERVER_BIND_ADDRESS=0.0.0.0
SERVER_HTTP_DEBUG_PORT=8080
SERVER_HTTP_TLS_PORT=7443
BACKEND_TLS=true
SERVER_HTTP_MAX_WRITE_TIMEOUT=5m
SERVER_HTTP_MAX_READ_TIMEOUT=5m
USE_WEBSOCKETS=true

Use the BACKEND_ADDRESS variable to point to the endpoint URL of your node.
Use the EXTERNAL_ADDRESS to select the web proxy URL that you will use to access the node from your console.
Use the SERVER_HTTP_TLS_PORT to select the port that you will use the access the web proxy.
You also need to provide a TLS certificate and key that will be used secure the communication between your console and web proxy. It is recommended that you use certificates that were issued to secure the domain name of your cluster. The common name of the TLS certificates must be the domain name of your web proxy URL. The TLS certificates then need be mounted inside the web proxy container. Use SERVER_TLS_CERT_FILE to point to the certificate and SERVER_TLS_KEY_FILE to point to the accompanying private key.

The console needs to check the health of any node being imported into the console. As a result, you need to enable the operations service for every node that is connected to a web proxy. For more information, see The Operations Service.

After the web proxy container is deployed, you can import the node into a console by creating a node JSON file. For more information about how to create the node file, see Importing nodes from a locally deployed network. You need to use the following values when you create the file:

Use the web proxy URL and port for the "grpcwp_url" field. You specified these values with the EXTERNAL_ADDRESS and SERVER_HTTP_TLS_PORT environment variables.
Use the node endpoint URL and port for the "api_url" field. You specified these values with the BACKEND_ADDRESS environment variable.
Encode the public TLS certificate of the node in base64 format and paste it in the"pem" field. This certificate was referenced by the SERVER_TLS_CLIENT_CA_FILES environment variable.

We deploy an example web proxy using Docker Compose as part of the example provided below. While the example is not a template for deploying a web proxy in production, it can be used for additional context on how you would connect a proxy to a running node.

Example

We can provide an example of the changes you need to make by updating the first-network sample to run the IBM Blockchain images instead of the community Docker images. The example is provided for context, and is not a template for deploying a production network.

You need to update the peer-base.yaml and docker-compose-base.yaml that are in the fabric-samples/first-network/base folder. You can find the orderer section of the peer-base.yaml below:

orderer-base:
  image: hyperledger/fabric-orderer:$IMAGE_TAG
  environment:
    - FABRIC_LOGGING_SPEC=INFO
    - ORDERER_GENERAL_LISTENADDRESS=0.0.0.0
    - ORDERER_GENERAL_GENESISMETHOD=file
    - ORDERER_GENERAL_GENESISFILE=/var/hyperledger/orderer/orderer.genesis.block
    - ORDERER_GENERAL_LOCALMSPID=OrdererMSP
    - ORDERER_GENERAL_LOCALMSPDIR=/var/hyperledger/orderer/msp
    # enabled TLS
    - ORDERER_GENERAL_TLS_ENABLED=true
    - ORDERER_GENERAL_TLS_PRIVATEKEY=/var/hyperledger/orderer/tls/server.key
    - ORDERER_GENERAL_TLS_CERTIFICATE=/var/hyperledger/orderer/tls/server.crt
    - ORDERER_GENERAL_TLS_ROOTCAS=[/var/hyperledger/orderer/tls/ca.crt]
    - ORDERER_KAFKA_TOPIC_REPLICATIONFACTOR=1
    - ORDERER_KAFKA_VERBOSE=true
    - ORDERER_GENERAL_CLUSTER_CLIENTCERTIFICATE=/var/hyperledger/orderer/tls/server.crt
    - ORDERER_GENERAL_CLUSTER_CLIENTPRIVATEKEY=/var/hyperledger/orderer/tls/server.key
    - ORDERER_GENERAL_CLUSTER_ROOTCAS=[/var/hyperledger/orderer/tls/ca.crt]
  working_dir: /opt/gopath/src/github.com/hyperledger/fabric
  command: orderer

To deploy an ordering node by using the IBM Blockchain image, change the image field to the tag of the IBM Blockchain image, cp.icr.io/cp/ibp-orderer:1.4.12-20230228-amd64. Accept the license by adding the field of LICENSE=accept. You then need to add the FABRIC_CFG_PATH environment variable and set the path to the folder where you mount the configuration files. Set the working_dir variable to the same path. After your changes, the orderer section would look like the example below:

orderer-base:
  image: cp.icr.io/cp/ibp-orderer:1.4.12-20230228-amd64
  environment:
    - LICENSE=accept
    - FABRIC_CFG_PATH=/etc/hyperledger/fabric
    - FABRIC_LOGGING_SPEC=INFO
    - ORDERER_GENERAL_LISTENADDRESS=0.0.0.0
    - ORDERER_GENERAL_GENESISMETHOD=file
    - ORDERER_GENERAL_GENESISFILE=/var/hyperledger/orderer/orderer.genesis.block
    - ORDERER_GENERAL_LOCALMSPID=OrdererMSP
    - ORDERER_GENERAL_LOCALMSPDIR=/var/hyperledger/orderer/msp
    # enabled TLS
    - ORDERER_GENERAL_TLS_ENABLED=true
    - ORDERER_GENERAL_TLS_PRIVATEKEY=/var/hyperledger/orderer/tls/server.key
    - ORDERER_GENERAL_TLS_CERTIFICATE=/var/hyperledger/orderer/tls/server.crt
    - ORDERER_GENERAL_TLS_ROOTCAS=[/var/hyperledger/orderer/tls/ca.crt]
    - ORDERER_KAFKA_TOPIC_REPLICATIONFACTOR=1
    - ORDERER_KAFKA_VERBOSE=true
    - ORDERER_GENERAL_CLUSTER_CLIENTCERTIFICATE=/var/hyperledger/orderer/tls/server.crt
    - ORDERER_GENERAL_CLUSTER_CLIENTPRIVATEKEY=/var/hyperledger/orderer/tls/server.key
    - ORDERER_GENERAL_CLUSTER_ROOTCAS=[/var/hyperledger/orderer/tls/ca.crt]
  working_dir: /etc/hyperledger/fabric
  command: orderer

If you are deploying a peer, you can make the same changes to the peer section of the peer-base.yaml file. However, you need add the core chaincode variables and specify images that you downloaded from IBM as the chaincode builder and the runtime environment. You also need to set DYNAMICLINK=true After your changes, the peer section would look like the example below:

services:
  peer-base:
    image: cp.icr.io/cp/ibp-peer:1.4.12-20230228-amd64
    environment:
      - LICENSE=accept
      - FABRIC_CFG_PATH=/etc/hyperledger/fabric
      - CORE_CHAINCODE_BUILDER=cp.icr.io/cp/ibp-ccenv:1.4.12-20230228-amd64
      - CORE_CHAINCODE_GOLANG_RUNTIME=cp.icr.io/cp/ibp-goenv:1.4.12-20230228-amd64
      - CORE_CHAINCODE_NODE_RUNTIME=cp.icr.io/cp/ibp-nodeenv:1.4.12-20230228-amd64
      - CORE_CHAINCODE_GOLANG_DYNAMICLINK=true
      - CORE_CHAINCODE_NODE_DYNAMICLINK=true
      - CORE_VM_ENDPOINT=unix:///host/var/run/docker.sock
      # the following setting starts chaincode containers on the same
      # bridge network as the peers
      # https://docs.docker.com/compose/networking/
      - CORE_VM_DOCKER_HOSTCONFIG_NETWORKMODE=${COMPOSE_PROJECT_NAME}_byfn
      - FABRIC_LOGGING_SPEC=INFO
      #- FABRIC_LOGGING_SPEC=DEBUG
      - CORE_PEER_TLS_ENABLED=true
      - CORE_PEER_GOSSIP_USELEADERELECTION=true
      - CORE_PEER_GOSSIP_ORGLEADER=false
      - CORE_PEER_PROFILE_ENABLED=true
      - CORE_PEER_TLS_CERT_FILE=/etc/hyperledger/fabric/tls/server.crt
      - CORE_PEER_TLS_KEY_FILE=/etc/hyperledger/fabric/tls/server.key
      - CORE_PEER_TLS_ROOTCERT_FILE=/etc/hyperledger/fabric/tls/ca.crt
    working_dir: /etc/hyperledger/fabric
    command: peer node start

The files that are mounted into the peer and orderer containers are specified in the docker-compose-base.yaml file. In the volumes: section, you can add the following line ../../config:/etc/hyperledger/fabric to mount the peer and orderer configuration files that are located in the fabric-samples directory. You need to remove the PKCS11 section of the fabric-samples/config/core.yaml file. The ledger data folder is mounted in the /var/hyperledger/production. We need to change this path to an existing folder to change the permissions of that folder. After your changes, docker-compose-base.yaml would look like the example below for an ordering node and one of your peers:

orderer.example.com:
  container_name: orderer.example.com
  extends:
    file: peer-base.yaml
    service: orderer-base
  volumes:
      - ../channel-artifacts/genesis.block:/var/hyperledger/orderer/orderer.genesis.block
      - ../crypto-config/ordererOrganizations/example.com/orderers/orderer.example.com/msp:/var/hyperledger/orderer/msp
      - ../crypto-config/ordererOrganizations/example.com/orderers/orderer.example.com/tls/:/var/hyperledger/orderer/tls
      - ../crypto-config/ordererOrganizations/example.com/orderers/orderer.example.com:/var/hyperledger/production/orderer
      - ../../config:/etc/hyperledger/fabric
  ports:
- 7050:7050

peer0.org1.example.com:
  container_name: peer0.org1.example.com
  extends:
    file: peer-base.yaml
    service: peer-base
  environment:
    - CORE_PEER_ID=peer0.org1.example.com
    - CORE_PEER_ADDRESS=peer0.org1.example.com:7051
    - CORE_PEER_LISTENADDRESS=0.0.0.0:7051
    - CORE_PEER_CHAINCODEADDRESS=peer0.org1.example.com:7052
    - CORE_PEER_CHAINCODELISTENADDRESS=0.0.0.0:7052
    - CORE_PEER_GOSSIP_BOOTSTRAP=peer1.org1.example.com:8051
    - CORE_PEER_GOSSIP_EXTERNALENDPOINT=peer0.org1.example.com:7051
    - CORE_PEER_LOCALMSPID=Org1MSP
  volumes:
      - /var/run/:/host/var/run/
      - ../crypto-config/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/msp:/etc/hyperledger/fabric/msp
      - ../crypto-config/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls:/etc/hyperledger/fabric/tls
      - ../crypto-config/peerOrganizations/org1.example.com/peers/peer0.org1.example.com:/var/hyperledger/production
      - ../../config:/etc/hyperledger/fabric
  ports:
    - 7051:7051

After you edit the file, you need to change the security permissions of the folders that are mounted to store your certificates and ledger data. Your peer MSP folder and TLS certificates are both stored in the crypto-config folder that is created when you run ./byfn.sh generate. To simplify the deployment, the example also mounts a folder in this directory to store our ledger data. You can run the following commands to generate the crypto material and folders, and then provide those folders the required permissions:

./byfn.sh generate
chmod -R 777 crypto-config

If you want to deploy a raft ordering service, you need to make the same edits to the docker-compose-etcdraft2.yaml file that you made to the order section of docker-compose-base.yaml. You need to create ledger folders for each ordering node and change the permissions of each folder.

After you update the relevant files, you can test that you can deploy your images by running the following command:

sudo ./byfn.sh up -i 1.4.12

You can use the updates that are provided in this example to deploy the IBM Blockchain images in the environment of your choice. The Fabric samples that are published by the Hyperledger community are intended to be used only as examples. Do not use the samples as templates for deploying production networks.

Deploying an IBM Blockchain Certificate Authority

The first-network sample does not use Certificate Authorities to deploy the network. However, you can find a file below that you can use to deploy an IBM Blockchain Certificate Authority using Docker Compose. If you want to deploy a CA as part of the example, you should use this file instead of editing the docker-compose-ca.yaml file in the first-network directory, which deploys a CA using existing crypto material. Save the following file as docker-compose-ibm-ca.yaml:

version: '2'

networks:
  byfn:

services:

  ca-org1:
    image: cp.icr.io/cp/ibp-ca:1.4.12-20230228-amd64
    environment:
      - LICENSE=accept
      - FABRIC_CA_HOME=/etc/hyperledger/fabric-ca-server
      - FABRIC_CA_SERVER_CA_NAME=ca-org1
      - FABRIC_CA_SERVER_TLS_ENABLED=true
      - FABRIC_CA_SERVER_PORT=7054
    ports:
      - "7054:7054"
    command: sh -c 'fabric-ca-server start -b admin:adminpw -d'
    volumes:
      - fabric-ca-config:/etc/hyperledger/fabric-ca-server
    container_name: ca_org1

You need to mount a copy of the Fabric CA server configuration file in the CA container. Create a folder named fabric-ca-config and save a copy of the Fabric CA server configuration file inside as fabric-ca-server-config.yaml. Update the sample file with information about your organization and the domain name of your CA. The Docker compose file will use this file to start the Fabric CA server and set the username and password of your CA admin to admin and adminpw. You can find more information about the Fabric CA server in the Fabric CA users guide. After you have saved docker-compose-ibm-ca.yaml and the configuration file, you can deploy the CA using the following command:

docker-compose -f docker-compose-ibm-ca.yaml up

When the CA is deployed, you can use the Fabric CA client or the Fabric SDKs to register new identities and generate certificates. For more information about how you would set up a blockchain network by using Certificate Authorities, see the Fabric CA Operations guide.

Deploying the gRPC web proxy

After we deploy a network, we can use the gRPC web proxy to import a peer or ordering node into an instance of the IBM Blockchain Platform console. Assuming that you downloaded the gRPC web proxy image, you can use the instructions below to connect a web proxy peer0.org1.example.com.

You need to enable the operations service for the peer. This will allow the console to check if the peer or ordering node is healthy before it connects to the node. To enable the operations service for peer0.org1.example.com, add the following environment variables to the to the peer0.org1.example.com section of docker-composer-base.yaml:
```
- CORE_OPERATIONS_LISTENADDRESS=0.0.0.0:9443
- CORE_OPERATIONS_TLS_ENABLED=false
```
You can also need to add the 9443 to the list of ports exposed by the peer.
```
 ports:
 - 7051:7051
 - 9443:9443
```
You need TLS certificates and keys to secure communication between your the console and your node. Create a folder that you will use for the TLS material and change into that directory.
```
mkdir peer0.org1-proxy-certs
cd peer0.org1-proxy-certs
```
This folder will be mounted in the gRPC web proxy container in a later step.

In a production environment, you would use the TLS certificates that secure the domain name of your deployment environment. For this example, we will generate self signed certificates using the OpenSSL tool.

Use the following command to generate a private key:

openssl genrsa -out private.key 4096

Create a ssl.conf file using the template below. Replace the _default variables with the values of your choice. Use the alt_names section to provide the domain of your cluster. This domain needs to match the public URL that you will select for the web proxy.

extensions = extend

[extend] # openssl extensions
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always
keyUsage = digitalSignature,keyEncipherment #Required by macOS Catalina
extendedKeyUsage=serverAuth,clientAuth

[ req ]
default_bits       = 4096
distinguished_name = req_distinguished_name
req_extensions     = req_ext

[ req_distinguished_name ]
countryName                 = Country Name (2 letter code)
countryName_default         = US
stateOrProvinceName         = State or Province Name (full name)
stateOrProvinceName_default = North Carolina
localityName                = Locality Name (eg, city)
localityName_default        = Durham
organizationName            = Organization Name (eg, company)
organizationName_default    = DevCorp
commonName                  = Common Name (e.g. server FQDN or YOUR name)
commonName_max              = 64
commonName_default          = John Doe (development)

[ req_ext ]
subjectAltName = @alt_names

[alt_names]
DNS.1   = web_proxy.peer0.org1.example.com
DNS.2   = *.example.com

Use the ssl.conf file and your private key to create a certificate signing request. Click enter to accept all the values you provided using the _default variables.

openssl req -new -sha256 -out private.csr -key private.key -config ssl.conf

Create the certificate:

openssl x509 -req -sha256 -days 3650 -in private.csr -signkey private.key -out public.crt -extensions req_ext -extfile ssl.conf

In addition to the TLS certificates used by the proxy, the web proxy also needs the public TLS certificate used by the peer or ordering node. Use the following command to copy the peer0.org1.example.com TLS certificate into your the current folder.
```
cp ../crypto-config/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt ca.crt
```
After copying the TLS certificate, the peer0.org1-proxy-certs should contain the peer TLS certificate and the web proxy TLS certificate and key:
```
$ ls
ca.crt        private.csr    private.key    public.crt    ssl.conf
```

Change back into the main directory of the BYFN example and save the following Docker Compose file for the gRPC web proxy image as docker-compose-proxy:

 version: '2'

 networks:
   byfn:

 services:
   web_proxy.peer0.org1.example.com:
     container_name: web_proxy.peer0.org1.example.com
     image: cp.icr.io/cp/ibp-grpcweb:1.4.12-20230228-amd64
     environment:
       - LICENSE=accept
       - BACKEND_ADDRESS=peer0.org1.example.com:7051
       - EXTERNAL_ADDRESS=web_proxy.peer0.org1.example.com:8443
       - SERVER_TLS_CERT_FILE=/certs/tls/public.crt
       - SERVER_TLS_KEY_FILE=/certs/tls/private.key
       - SERVER_TLS_CLIENT_CA_FILES=/certs/tls/ca.crt
       - SERVER_BIND_ADDRESS=0.0.0.0
       - SERVER_HTTP_DEBUG_PORT=8080
       - SERVER_HTTP_TLS_PORT=8443
       - BACKEND_TLS=true
       - SERVER_HTTP_MAX_WRITE_TIMEOUT=5m
       - SERVER_HTTP_MAX_READ_TIMEOUT=5m
       - USE_WEBSOCKETS=true
     ports:
       - "8443:8443"
     volumes:
       - ./peer0.org1-proxy-certs:/certs/tls
     networks:
       - byfn

The Docker Compose file mounts the folder where we stored the TLS certificates in the web proxy container inside a folder named certs/tls. We need to specify several important environment variables that point to the certificates inside this folder:

SERVER_TLS_CERT_FILE needs to point to the certificate you created using OpenSSL.
SERVER_TLS_KEY_FILE needs to point to the private key that you created using OpenSSL.
SERVER_TLS_CLIENT_CA_FILES needs to point to the node TLS certificate.

You also need to specify the public URL of the peer and the web proxy:

BACKEND_ADDRESS needs to point to the public endpoint of your peer that is used by client applications, peer0.org1.example.com:7051.
Use the EXTERNAL_ADDRESS variable select the URL and port that will be used to access the web proxy. This URL and port needs to be accessible by external traffic.

Before we bring up the proxy, we need to create a JSON file used to import the peer into our console. Save the following file as peer0.org1.json

{
"name": "peer.org1.exaple.com",
"grpcwp_url": "https://web_proxy.peer0.org1.example.com:8443",
"api_url": "grpcs://peer0.org1.example.com:7051",
"operations_url": "https://peer0.org1.example.com:9443",
"type": "fabric-peer",
"msp_id": "org1msp",
"pem": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNGekNDQWI2Z0F3SUJBZ0lVUi9zMGxGTG5ZNmdWRmV1Mlg5ajkrY3JDZFBrd0NnWUlLb1pJemowRUF3SXcKWFRFTE1Ba0dBMVVFQmhNQ1ZWTXhGekFWQmdOVkJBZ1REazV2Y25Sb0lFTmhjbTlzYVc1aE1SUXdFZ1lEVlFRSwpFd3RJZVhCbGNteGxaR2RsY2pFUE1BMEdBMVVFQ3hNR1JtRmljbWxqTVE0d0RBWURWUVFERXdWMGJITmpZVEFlCkZ3MHhPVEEyTVRBeE9USXhNREJhRncwek5EQTJNRFl4T1RJeE1EQmFNRjB4Q3pBSkJnTlZCQVlUQWxWVE1SY3cKRlFZRFZRUUlFdzVPYjNKMGFDQkRZWEp2YkdsdVlURVVNQklHQTFVRUNoTUxTSGx3WlhKc1pXUm5aWEl4RHpBTgpCZ05WQkFzVEJrWmhZbkpwWXpFT01Bd0dBMVVFQXhNRmRHeHpZMkV3V1RBVEJnY3Foa2pPUFFJQkJnZ3Foa2pPClBRTUJCd05DQUFUYUtyN2srUHNYeXFkWkdXUHlJUXlGMGQxUkFFdmdCYlpkVnlsc3hReWZOcUdZS0FZV3A0SFUKVUVaVHVVNmtiRXN5Qi9aOVJQWEY0WVNGbW8reTVmSkhvMXd3V2pBT0JnTlZIUThCQWY4RUJBTUNBUVl3RWdZRApWUjBUQVFIL0JBZ3dCZ0VCL3dJQkFUQWRCZ05WSFE0RUZnUVUrcnBNb2dRc3dDTnZMQzJKNmp2cElQOExwaE13CkZRWURWUjBSQkE0d0RJY0VDUjc4YTRjRXJCRE5DakFLQmdncWhrak9QUVFEQWdOSEFEQkVBaUJGWmpMWU9XZUMKLy92L2RNMHdYNUxZT3NCaHFFNnNQZ1BSWWppOTZqT093QUlnZEppZDU0WmxjR2h0R3dEY3ZoZE02RVlBVFpQNwpmS29IMDZ3ZFhpK3VzVXM9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K",
"location": "mycluster"
}

Use the following values to complete the file:

"name": The display name for the peer in the IBM Blockchain Platform console.
"grpcwp_url": The external address of the web proxy that you selected using the EXTERNAL_ADDRESS variable.
"api_url": The public address of the node used by your client applications and is specified in the BACKEND_ADDRESS variable.
"operations_url": The URL and port that was opened for the operations service. We used the CORE_OPERATIONS_LISTENADDRESS variable to specify that the operations service will use port 9443 in step one. As a result, the console can use the address https://peer0.org1.example.com:9443 to check the health of our peer.
"type": select fabric-peer, fabric-orderer, or fabric-ca.
"msp_id": The MSPID of the organization that operates the node.
"location": Location of your choice.
"pem" The node TLS certificate encoded in Base64 format. We copied the peer TLS certificate into the peer0.org1-proxy-cert folder. We can encode the certificate using the following command:

export FLAG=$(if [ "$(uname -s)" == "Linux" ]; then echo "-w 0"; else echo "-b 0"; fi)
cat peer0.org1-proxy-certs/ca.crt | base64 $FLAG

Bring up the web proxy using the following command:

docker-compose -f docker-compose-proxy.yaml up

If the web proxy is created successfully, you should see messages in your logs similar to the following:

web_proxy.peer0.org1.example.com    | time="2020-01-29T22:18:37Z" level=info msg="listening for http_tls on: [::]:8443"
web_proxy.peer0.org1.example.com    | time="2020-01-29T22:18:37Z" level=info msg="listening for http on: [::]:8080"

You can now view the node from a console by importing the peer0.org1.json file into an IBM Blockchain Platform console deployed on IBM Cloud or your own cluster using IBM Blockchain Platform 2.5.3. In order for the console to access your nodes, the URL of the web proxy, the peer, and the operations URL needs be externally accessible.

You need to complete these steps for each node that you want to import into an instance of the IBM Blockchain Platform console.

Interoperability

Nodes that are deployed by using the IBM Blockchain images can join the channels of other IBM Blockchain offerings, such as IBM Blockchain Platform 2.5.3 and IBM Blockchain Platform for IBM Cloud. Unless you connected an instance of the gRPC web proxy to the node, you cannot use the console to operate the images. You need to use Fabric tools to join existing channels that were created with a console or create new channels.

Upgrading to new versions

You can upgrade your deployment to the latest version of the IBM Blockchain images. The latest images contain improvements or use a later version of Hyperledger Fabric, allowing you to take advantage of the latest Fabric features. To upgrade your network, you need to back up the ledger and MSP data for each node and then manually upgrade the node binaries. For more information about upgrading a network that you deployed using the IBM Blockchain images, see Upgrading Your Network Components in the Hyperledger Fabric documentation.

Getting support

If you encounter issues that are related to Hyperledger Fabric or the underlying images, you can submit a support case from the mysupport page. When you open a case you need to select your product, IBM Blockchain Platform 2.5.3.

IBM provides support for issues that are related to the Hyperledger Fabric code or the steps to download and deploy the images that you can find in this documentation. IBM does not provide support for issues that relate to the operation of the images or your underlying infrastructure. Deployment issues due to the specific circumstances of the customer environment will be the customer's responsibility to investigate. If you need assistance with the deployment and management of a Fabric network, use the IBM Blockchain Platform 2.5.3 offering.

You can take advantage of free blockchain developer resources and support forums to troubleshoot problems and get help from IBM and the Fabric community. For more information, see Resources and support forums.