Remote Enterprise Node (peerpay-enterprise-blockchain)

The peerpay-enterprise-blockchain repository provides a standardised approach for deploying a new Hyperledger Fabric peer on an external, remote server (such as an AWS EC2 instance owned by an enterprise partner).

At a Glance

Property Value
Role Remote / federated Fabric peer
Stack Hyperledger Fabric peer image, Docker Compose, Make
Identity TLS + MSP material generated by the master network's CA
Channels joined bankloan-channel, p2p-channel
Default ports Peer 7051, chaincode 7052, CouchDB 5984 (override if running side-by-side with the master)

Purpose

To make the network truly decentralised, external organisations must be able to deploy their own peer nodes on their own infrastructure. This repository simplifies that process by giving enterprise partners the automated scripts they need to spin up a node, import generated identity keys, and join the PeerPay channels.

Prerequisites

  • An EC2 (or equivalent) host with Docker, Docker Compose v2 and Make installed.
  • Network reachability to the master node's public IP / DNS over the Fabric gRPC ports.
  • A crypto bundle generated by the master node specifically for this peer's hostname.
  • A populated .env (using .env.template as the starting point).

Detailed Setup and Running Process

Connecting a new remote peer happens in four phases.

Phase 1 — Generate Crypto on the Master Node

On the master node, generate the cryptographic material for the new peer:

# 1. Navigate to the fabric directory
cd deployment-github/peerpay-fabric

# 2. Generate the tarball for the new peer.
#    PEER_HOST is required (public DNS name for this peer, e.g. dev.core.peerpaynetwork.com).
#    Output archive: generated-crypto-material/<PEER_HOST>-crypto.tar.gz
make generate-remote-peer-crypto ORG=<orgN> PEER_NUM=<peer_number> PEER_HOST=<your.peer.hostname>

Phase 2 — Transfer the Materials

Securely copy the generated .tar.gz from the master node to the remote node's peerpay-enterprise-blockchain directory. Run this from any terminal that has SSH access to both, or directly from the master node:

scp generated-crypto-material/<your.peer.hostname>-crypto.tar.gz \
    user@<REMOTE_SERVER_IP>:/path/to/deployment-github/peerpay-enterprise-blockchain/

Replace <your.peer.hostname> with the PEER_HOST value used above, and <REMOTE_SERVER_IP> and /path/to/... with the actual remote server IP and path.

Crypto material is sensitive

The .tar.gz archive contains TLS keys and the peer's private MSP material. Treat it like a password: transfer over SSH only, never email it, and delete it from intermediate hosts as soon as the peer is up.

Phase 3 — Run Setup on the Remote Node

SSH into the new remote server, unpack the credentials, and join it to the master network:

# 1. Navigate to the new node setup folder
cd deployment-github/peerpay-enterprise-blockchain

# 2. Extract the cryptographic materials into ./crypto-config
make extract-crypto ARCHIVE=<your.peer.hostname>-crypto.tar.gz

# 3. Copy the environment variable template
cp .env.template .env

# 4. Edit the .env file
#    - Use the values produced by the frontend "Generate Env Credentials" action for the same org/peer.
#    - Replace <Replace_With_AWS_IP> with the public IP / DNS of the master node's EC2 instance.
#      (If you are testing this locally on the same machine, use your local network IP, e.g. 192.168.x.x.)
#    - IMPORTANT: if testing locally on the same machine as the master node, you MUST change
#      PEER_PORT (e.g. 8051), CHAINCODE_PORT (e.g. 8052) and COUCHDB_PORT (e.g. 6984) to avoid conflicts.
nano .env

# 5. Deploy the peer container and automatically join it to the channels
make setup-peer-for-node

# 6. Remove the generated crypto materials from the master node
make remove-generated-remote-peer PEER_HOST=<your.peer.hostname>

# 7. Restart the API on the master node so it picks up the new peer
docker compose restart fabric-api

Phase 4 — Verification (Optional)

Verify the new peer is healthy and syncing channels:

# View the live Docker logs of the new peer
make logs

# List peers in the network
make list-peers

# Verify channel membership
make channel-orgs CHANNEL=bankloan-channel
make channel-orgs CHANNEL=p2p-channel

# Verify TLS connections
make verify-tls

Communication

  • Connecting to the network — because this node lives outside the master node's local network, it requires public internet connectivity. The remote node connects to the master node's public IP address or DNS hostname (e.g. dev.core.peerpaynetwork.com).
  • Gossip protocol — once connected to the orderers and other peers via gRPC over TLS, the remote peer uses Fabric's Gossip protocol to rapidly synchronise ledger blocks. It pulls transaction history and state databases without needing constant central orchestration.
  • Endorsement participation — depending on each channel's endorsement policy, the remote peer may also be asked to endorse new transactions.

Troubleshooting

  • Peer cannot join the channel — verify time synchronisation (NTP) on the remote host. Fabric is strict about clock skew. Confirm that the master orderer's 7050 port is reachable from the remote host.
  • TLS handshake failures — confirm the certificate's Subject Alternative Names (SANs) match the public DNS name you set as PEER_HOST. Re-generating the crypto bundle with the correct PEER_HOST is the usual fix.
  • CouchDB conflicts when running on the same host as the master — make sure you changed COUCHDB_PORT (and PEER_PORT, CHAINCODE_PORT) in .env to avoid colliding with the master containers.