Fablo Configuration File Reference

Table of Contents

1. Overview
2. $schema — schema URL for the config
3. global — network-wide settings (Fabric version, TLS, engine, provider, images, monitoring, tools)
4. orgs — organization definitions (CA, orderers, peers, tools)
5. channels — channel definitions and organization/peer membership
6. chaincodes — chaincode definitions, endorsement, and private data collections
7. hooks — commands run after generate / start

Overview

A Fablo configuration file is a JSON or YAML document. Required top-level sections: global, orgs, channels, and chaincodes. Optional top-level fields: $schema and hooks.

Commands that take an optional config path, such as fablo up and fablo validate, look for fablo-config.json in the current directory, and fall back to fablo-config.yaml if the JSON file is not there.

This page covers the main fields used in practice. For the full JSON Schema (including schema-only defaults), see schema.json. Note that some schema defaults (for example Fabric 2.4.2 or a solo orderer) are stale relative to what fablo init generates today, so prefer the fablo init defaults below when starting a new network.

What fablo init generates today: Fabric 3.1.0, TLS on, engine docker, an Orderer organization with two BFT orderers in group group1, an Org1 organization with two LevelDB peers, channel my-channel1, and empty chaincodes and hooks. The generated channel has no ordererGroup, so it falls back to the first orderer group. fablo init fabric-x writes a different starter config, described under global.provider.

$schema

fablo init sets this to the schema for the Fablo release you are running, for example:

"$schema": "https://github.com/hyperledger-labs/fablo/releases/download/<version>/schema.json"

fablo validate reads the version out of the URL and reports an error when it does not match the Fablo release you are running, so update $schema when you upgrade Fablo.

global

Basic settings of the Hyperledger Fabric network. Type: object. Required fields: fabricVersion, tls.

global.provider

Selects the network provider. The default is fabric, which is the fully supported Hyperledger Fabric network. The value fabric-x selects the experimental Fabric-X provider, and fablo init fabric-x writes a starter config that uses it.

When provider is fabric-x, fablo validate reports an error for any of the following:

• engine is kubernetes, because Fabric-X supports docker only
• tls is false, because Fabric-X requires TLS
• peerDevMode is true
• Explorer or Fablo REST is enabled, in global.tools or in any orgs[].tools
• chaincodes is not empty, because the Fabric-X provider does not deploy chaincodes yet
• channels does not hold exactly one channel

global.fabricImages

Optional Docker images for Hyperledger Fabric components.

The defaults above are repository names without a tag. When you give an image with no tag and no digest, Fablo appends a tag it derives from fabricVersion, so myregistry/fabric-peer becomes myregistry/fabric-peer:3.1.0 on a Fabric 3.1.0 network. Give the image with a tag or a digest to pin it yourself.

global.monitoring

Optional settings for monitoring purposes.

global.tools

Explorer is supported on Fabric v2 only, not on Fabric v3 (including the default 3.1.0 init config). See SUPPORTED_FEATURES.md.

When global.tools.explorer is true, Fablo runs one Explorer for the whole network and ignores the orgs[].tools.explorer setting on each organization. fablo validate warns about each organization whose setting is ignored this way.

Example

"global": {
  "fabricVersion": "3.1.0",
  "tls": true,
  "peerDevMode": false
}

orgs

An array of organization definitions. Type: array. Each item’s required field: organization.

orgs[].organization

Basic information about the organization. Required fields: name, domain.

orgs[].ca

Organization Certificate Authority (CA) settings.

orgs[].orderers

An array of orderer group definitions for this organization. Each item requires groupName, type, instances. Organizations without orderers omit this field or use an empty array.

Notes:

• solo is for Fabric v2 development only; it is not supported on Fabric v3. With solo, only one instance is created, and fablo validate warns if instances is greater than 1.
• raft requires global.tls to be true.
• BFT requires Fabric v3.
• An organization may have at most 9 orderers in total across all of its groups.
• groupName must be unique within an organization, and every orderer in a group must use the same type, even when the group spans several organizations.
• fablo init creates one orderer group: groupName: "group1", type: "BFT", instances: 2.

orgs[].peer

Peer settings for this organization. If a peer object is present, instances is required within it. Orderer-only organizations (such as orgs[0] from fablo init) typically have no peer block.

Peers are named after the prefix followed by a zero based index, so the default prefix gives peer0, peer1 and so on. The first anchorPeerInstances peers become anchor peers, and because the default is the value of instances, every peer is an anchor peer unless you set a lower number. fablo validate reports an error when anchorPeerInstances is greater than instances.

orgs[].tools

Fablo REST is a separate REST API client for CA and chaincodes. It is not the same as the optional Node.js gateway sample copied by fablo init gateway. Explorer is Fabric v2 only.

Fablo REST cannot be used together with global.peerDevMode, and fablo validate reports an error for each organization that enables both. Peers in dev mode do not expose their chaincodes through the discovery service, which Fablo REST needs.

Example

"orgs": [
  {
    "organization": {
      "name": "Orderer",
      "mspName": "OrdererMSP",
      "domain": "orderer.example.com"
    },
    "ca": { "prefix": "ca", "db": "sqlite" },
    "orderers": [
      { "groupName": "group1", "prefix": "orderer", "type": "BFT", "instances": 2 }
    ]
  },
  {
    "organization": {
      "name": "Org1",
      "mspName": "Org1MSP",
      "domain": "org1.example.com"
    },
    "ca": { "prefix": "ca", "db": "sqlite" },
    "orderers": [],
    "peer": { "prefix": "peer", "instances": 2, "db": "LevelDb" }
  }
]

channels

An array of channel definitions. Type: array. Each item’s required fields: name, orgs.

ordererGroup references an orderer group’s groupName, not an organization name. fablo validate reports an error when the value does not match a groupName defined in orgs. The pattern for ordererGroup allows letters and digits only, so it cannot reference a groupName that contains a dot or a hyphen.

channels[].orgs[]

Each item requires name and peers.

Each entry in peers is a peer name, which is the organization’s peer prefix followed by a zero based index, for example peer0. An organization listed here must have a peer block, so you cannot join an orderer-only organization to a channel.

Example

"channels": [
  {
    "name": "my-channel1",
    "ordererGroup": "group1",
    "orgs": [
      { "name": "Org1", "peers": ["peer0", "peer1"] }
    ]
  }
]

chaincodes

An array of chaincode definitions. Type: array. Each item’s required fields: name, version, lang, channel. Additionally, if lang is ccaas, image is required; otherwise directory is required.

Fablo chooses between init and initRequired from global.fabricVersion. On Fabric 2.x it uses initRequired, and fablo validate warns that init is ignored. From Fabric 3.0.0 up it uses init, and fablo validate warns that initRequired is ignored.

When you leave endorsement out, the default depends on global.fabricVersion as well. On Fabric 2.x Fablo sets no policy and Fabric applies its own default. From Fabric 3.0.0 up Fablo builds a policy that requires every organization on the channel, for example AND ('Org1MSP.member') for a channel with only Org1.

Constraints:

• chaincodeMountPath and chaincodeStartCommand are only valid when lang is ccaas. Using them with node / golang / java fails validation.
• lang: "ccaas" requires global.tls to be true. CCaaS without TLS is not supported yet.
• Chaincode names must be unique within a channel.
• fablo init ccaas cannot be combined with node or dev.
• Peer dev mode (global.peerDevMode / fablo init node dev) has Fabric-version limits; see SUPPORTED_FEATURES.md.

chaincodes[].privateData[]

Each item requires name and orgNames.

Every name in orgNames must be an organization that has joined the chaincode’s channel, not merely an organization defined in orgs. Fablo builds the collection policy as OR over the MSPs of the named organizations, for example OR('Org1MSP.member').

Example

"chaincodes": [
  {
    "name": "chaincode1",
    "version": "0.0.1",
    "lang": "node",
    "channel": "my-channel1",
    "endorsement": "AND ('Org1MSP.member')",
    "directory": "./chaincodes/chaincode-kv-node",
    "privateData": [
      { "name": "privateCollectionOrg1", "orgNames": ["Org1"] }
    ]
  }
]

CCaaS example:

{
  "name": "chaincode1",
  "version": "0.0.1",
  "lang": "ccaas",
  "channel": "my-channel1",
  "image": "ghcr.io/fablo-io/fablo-sample-kv-node-chaincode:2.2.0",
  "chaincodeStartCommand": "npm run start:ccaas"
}

hooks

Optional Bash commands run after specific events.

Fablo renders each hook into a script under fablo-target/hooks/ and runs it from the directory where you ran fablo, not from fablo-target. A relative path in a hook is resolved against your project directory, which is why the example below can use ./chaincodes/chaincode-kv-node.

Example

"hooks": {
  "postGenerate": "npm i --prefix ./chaincodes/chaincode-kv-node",
  "postStart": "echo network is up"
}