Skip to main content

​
Hyperledger Fabric Setup

This guide covers the complete setup of Hyperledger Fabric for document registry and audit traceability in CCDigital.
Fabric acts as a trust layer for document traceability. MySQL remains the primary transactional database, while Fabric provides immutable audit records.

​
Prerequisites

Before starting, ensure you have:
  • Docker and Docker Compose installed
  • curl, git, and jq utilities
  • Node.js LTS (for client scripts)
  • Fabric binaries (peer, orderer, configtxlator) for your selected version

​
Installation

1

Download Fabric Samples

Clone the official fabric-samples repository:
git clone https://github.com/hyperledger/fabric-samples.git
cd fabric-samples
2

Bootstrap Fabric

Run the official bootstrap script to download binaries and Docker images:
curl -sSL https://bit.ly/2ysbOFE | bash -s
Verify the binaries and image versions are compatible.
3

Stop Previous Networks

If you have a previous test network running, stop it:
cd test-network
./network.sh down

​
Network Setup

1

Start the Network

Launch the network with certificate authorities:
./network.sh up createChannel -ca
This creates a channel for business transactions and starts peers and orderers.
2

Verify Network Health

Confirm that peers and orderers are healthy:
docker ps
You should see containers for peers, orderers, and CAs running.
Ensure all containers are in a healthy state before proceeding to chaincode deployment.

​
Chaincode Deployment

1

Package Chaincode

Package your chaincode for deployment:
# Assuming your chaincode is in chaincode/ccdigital/
peer lifecycle chaincode package ccdigital.tar.gz \
  --path ./chaincode/ccdigital \
  --lang node \
  --label ccdigital_1
2

Install and Approve

Install the chaincode on required organizations and approve:
# Install on Org1
peer lifecycle chaincode install ccdigital.tar.gz

# Query installed chaincodes to get package ID
peer lifecycle chaincode queryinstalled

# Approve for Org1 (repeat for other orgs)
peer lifecycle chaincode approveformyorg \
  --channelID mychannel \
  --name ccdigital \
  --version 1.0 \
  --package-id <PACKAGE_ID> \
  --sequence 1
3

Commit Chaincode Definition

Commit the chaincode definition to the channel:
peer lifecycle chaincode commit \
  --channelID mychannel \
  --name ccdigital \
  --version 1.0 \
  --sequence 1
4

Validate Invocation

Test basic chaincode invocation:
peer chaincode query -C mychannel -n ccdigital -c '{"Args":["queryDocs","CC","123456"]}'

​
Client Integration

​
MSP Identity Configuration

Define the MSP identity used by the Node.js scripts: 
export CORE_PEER_LOCALMSPID="Org1MSP"
export CORE_PEER_MSPCONFIGPATH=/path/to/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp

​
TLS Configuration

export CORE_PEER_TLS_ENABLED=true
export CORE_PEER_TLS_ROOTCERT_FILE=/path/to/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt
export CORE_PEER_ADDRESS=localhost:7051

​
Integration Scripts

CCDigital uses the following Node.js scripts for Fabric integration. These are referenced in FabricLedgerCliService.java and ExternalToolsProperties.java.

​
Available Scripts

list-docs.js

Lists documents for a specific person from the ledger.Service: FabricLedgerCliServiceUsage:
node list-docs.js <idType> <idNumber>

sync-db-to-ledger.js

Synchronizes all documents from MySQL to Fabric ledger.Service: ExternalToolsServiceUsage:
node sync-db-to-ledger.js

read-block-by-ref.js

Reads block details using a functional reference (docId).Service: FabricAuditCliServiceConfiguration: external-tools.fabric.block-reader-script

record-access-event.js

Records audit events on-chain (verification/document access).Service: FabricAuditCliServiceConfiguration: external-tools.fabric.record-access-script

list-access-events.js

Lists audit events on-chain by person or globally.Configuration: external-tools.fabric.list-access-script

​
Sync Scripts

  • sync-all-script: Global synchronization from DB to ledger
  • sync-person-script: Per-person synchronization from DB to ledger

​
Environment Variables

Configure the following environment variables for Fabric integration: 
# Fabric working directory (where scripts are located)
export FABRIC_WORKDIR="/path/to/fabric-samples/test-network/client"

# Node.js binary
export FABRIC_NODE_BIN="node"

# Script paths
export FABRIC_LIST_DOCS_SCRIPT="list-docs.js"
export FABRIC_BLOCK_READER_SCRIPT="read-block-by-ref.js"
export FABRIC_RECORD_ACCESS_SCRIPT="record-access-event.js"
export FABRIC_LIST_ACCESS_SCRIPT="list-access-events.js"
export FABRIC_SYNC_ALL_SCRIPT="sync-db-to-ledger.js"
export FABRIC_SYNC_PERSON_SCRIPT="sync-person-to-ledger.js"

# Script execution timeout (seconds)
export EXTERNAL_TOOLS_TIMEOUT_SECONDS="180"
These variables are mapped in application.properties under the external-tools.fabric.* prefix.

​
Synchronization

​
Full Synchronization

From the Admin dashboard, you can trigger a full synchronization of MySQL data to the Fabric ledger: 
// AdminController.java - /admin/sync endpoint
ExternalToolsService.exec(syncAllScript, fabricWorkdir, env)

​
Per-Person Synchronization

Synchronize documents for a specific person: 
node sync-person-to-ledger.js <personId>

​
Query and Validation

​
Query Documents from Ledger

The FabricLedgerCliService provides methods to query documents: 
// List all documents for a person
List<FabricDocView> docs = fabricLedgerCliService.listDocsView("CC", "123456");

// Find specific document by ID
Optional<FabricDocView> doc = fabricLedgerCliService.findDocById("CC", "123456", "doc-001");

​
Verify Consistency

Validate that document IDs and states in the ledger match the MySQL database: 
# Query from Fabric
node list-docs.js CC 123456

# Compare with DB query
mysql -e "SELECT * FROM person_documents WHERE person_id = ...;"

​
Troubleshooting

​
Check Peer Logs

docker logs peer0.org1.example.com

​
Check Chaincode Logs

docker logs dev-peer0.org1.example.com-ccdigital_1

​
Verify Script Execution

Test script execution manually: 
cd $FABRIC_WORKDIR
node list-docs.js CC 123456
All script executions are handled by ExternalToolsService with configurable timeouts defined in EXTERNAL_TOOLS_TIMEOUT_SECONDS.

​
Service References

  • FabricLedgerCliService (src/main/java/co/edu/unbosque/ccdigital/service/FabricLedgerCliService.java:35): Main service for document queries
  • ExternalToolsService (src/main/java/co/edu/unbosque/ccdigital/service/ExternalToolsService.java): Generic script execution service
  • ExternalToolsProperties (src/main/java/co/edu/unbosque/ccdigital/config/ExternalToolsProperties.java:24): Configuration properties
  • FabricAuditCliService (src/main/java/co/edu/unbosque/ccdigital/service/FabricAuditCliService.java): Audit event recording
  • BlockchainTraceDetailService (src/main/java/co/edu/unbosque/ccdigital/service/BlockchainTraceDetailService.java): Blockchain trace details

​
Next Steps

Configure ACA-Py

Set up ACA-Py agents for credential issuance and verification

Hyperledger Indy Setup

Configure Indy ledger for identity credentials

Build docs developers (and LLMs) love

Get started for freeTalk to us