Create a Fabric-X Network

This guide walks you through creating a Fabric-X network from scratch using the ChainLaunch API. It mirrors what the quickstart wizard does automatically, but gives you full control over organizations, port assignments, and multi-network layouts.

Use this guide when:

• You need to pin ports (multiple Fabric-X networks on one host).
• You want a party count other than 4.
• You're integrating with existing organizations.
• You're provisioning from CI, a script, or Terraform.

Prerequisites

• ChainLaunch server running (default: http://localhost:8100).
• Docker Desktop or Docker Engine running and reachable.
• curl and jq installed.
• Admin credentials.

macOS / Windows — local development mode

If you're running ChainLaunch on macOS or Windows with Docker Desktop, set localDev: true when creating the network (see Step 4). This swaps the party external IP for host.docker.internal in the genesis block so containers can reach each other, and routes host-originated dials (namespace creation, explorer) through 127.0.0.1.

Alternatively, set this env var on the ChainLaunch server process to apply the same behavior globally to every Fabric-X network without touching the request body:

export CHAINLAUNCH_FABRICX_LOCAL_DEV=true

Per-network localDev takes precedence; the env var is the global fallback and stays for backward compatibility.

On Linux, leave both unset — the external IP is directly reachable from containers and nothing needs rewriting.

Shell helpers

export CL="http://localhost:8100"
export AUTH="admin:admin123"

Topology reference

A single N-party Fabric-X network needs:

Maximum supported partyId per network is 10.

Port allocation strategy

Each orderer group and committer exposes its components on the host. You have two options:

Auto-allocate (single network)

Omit port fields from the request body (or send 0). ChainLaunch picks from its free-port pool. Fine for a single Fabric-X network per host.

Pin ports (multi-network or production)

Reserve a 100-port band per network, with a 20-port slot per party inside. Example scheme for two networks, 4 parties each:

Rule of thumb:

• 100-port band per network: 17000 + 100*networkIndex
• 20-port slot per party within the band: band + 20*(partyIndex - 1)
• First 10 ports of a slot → orderer group; next 10 → committer

The only hard requirement is no two components share a host port.

Reusing organizations

Nothing forces a new org per network. If Party1MSP already exists from network A, you can pass the same organization ID when creating network B. The orderer groups and committers are per-network; the organization and its CAs are not.

Step 1 — Create organizations

Each org gets a signing CA and a TLS CA automatically.

for p in 1 2 3 4; do
  curl -s -u "$AUTH" -X POST "$CL/api/v1/organizations" \
    -H "Content-Type: application/json" \
    -d "{
      \"mspId\": \"Party${p}MSP\",
      \"description\": \"Fabric-X Party ${p}\",
      \"providerId\": 1
    }" | jq '.id, .mspId'
done

Capture each org ID — we'll use $ORG1..$ORG4 below.

export ORG1=$(curl -s -u $AUTH "$CL/api/v1/organizations" \
  | jq '.items[] | select(.mspId=="Party1MSP") | .id')
# repeat for ORG2..ORG4

Step 2 — Create orderer groups

One per party. This is the 4-container unit. Containers do not start yet.

curl -s -u "$AUTH" -X POST "$CL/api/v1/nodes" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"netA-orderer-p1\",
    \"nodeType\": \"FABRICX_ORDERER_GROUP\",
    \"fabricxOrdererGroup\": {
      \"name\": \"netA-orderer-p1\",
      \"organizationId\": $ORG1,
      \"mspId\": \"Party1MSP\",
      \"partyId\": 1,
      \"externalIp\": \"127.0.0.1\",
      \"version\": \"latest\",
      \"consenterType\": \"pbft\",
      \"routerPort\": 17010,
      \"batcherPort\": 17011,
      \"consenterPort\": 17012,
      \"assemblerPort\": 17013
    }
  }"

Repeat for parties 2, 3, 4 with their ports from the table above.

Validation rules:

• partyId must be between 1 and 10 and unique per network.
• mspId must match the organization's MSP ID.
• consenterType: "pbft" (default) or "raft".

Step 3 — Create committers

One per party. The 6-container unit. Again, containers do not start yet.

curl -s -u "$AUTH" -X POST "$CL/api/v1/nodes" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"netA-committer-p1\",
    \"nodeType\": \"FABRICX_COMMITTER\",
    \"fabricxCommitter\": {
      \"name\": \"netA-committer-p1\",
      \"organizationId\": $ORG1,
      \"mspId\": \"Party1MSP\",
      \"externalIp\": \"127.0.0.1\",
      \"version\": \"latest\",
      \"sidecarPort\":      17020,
      \"coordinatorPort\":  17021,
      \"validatorPort\":    17022,
      \"verifierPort\":     17023,
      \"queryServicePort\": 17024,
      \"postgresPort\":     17025,
      \"postgresHost\":     \"host.docker.internal\",
      \"postgresDb\":       \"netA_p1\",
      \"postgresUser\":     \"fabricx\",
      \"postgresPassword\": \"fabricx\",
      \"channelId\":        \"arma\",
      \"ordererEndpoints\": [
        \"host.docker.internal:17013\",
        \"host.docker.internal:17033\",
        \"host.docker.internal:17053\",
        \"host.docker.internal:17073\"
      ]
    }
  }"

Notes:

• postgresHost: host.docker.internal + a distinct postgresPort per committer gives each party its own postgres container.
• postgresDb must be unique per committer if they share a postgres instance (by default they don't).
• ordererEndpoints lists assembler ports, not router ports. The sidecar pulls blocks from assemblers.
• The channelId is always "arma" as of this writing.

Repeat for parties 2, 3, 4.

Step 4 — Create the network

This generates the Arma genesis block from the party list and stores it on the network row. No containers start yet.

curl -s -u "$AUTH" -X POST "$CL/api/v1/networks/fabricx" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"netA\",
    \"description\": \"Fabric-X network A (ports 17010-17099)\",
    \"config\": {
      \"channelName\": \"arma\",
      \"localDev\": false,
      \"organizations\": [
        {\"id\": $ORG1, \"ordererNodeId\": $OG1_ID, \"committerNodeId\": $CM1_ID},
        {\"id\": $ORG2, \"ordererNodeId\": $OG2_ID, \"committerNodeId\": $CM2_ID},
        {\"id\": $ORG3, \"ordererNodeId\": $OG3_ID, \"committerNodeId\": $CM3_ID},
        {\"id\": $ORG4, \"ordererNodeId\": $OG4_ID, \"committerNodeId\": $CM4_ID}
      ]
    }
  }" | jq '.id'

Request body fields:

Capture the returned network ID as $NETA_ID.

Step 5 — Join every node

This is the step that actually starts the containers. Each join writes the genesis block into the node's bind mount and calls StartNode.

NODE_IDS=$(curl -s -u "$AUTH" "$CL/api/v1/nodes?platform=FABRICX" \
  | jq -r '.items[] | select(.name | startswith("netA-")) | .id')
 
for nid in $NODE_IDS; do
  echo "Joining node $nid..."
  curl -s -u "$AUTH" --max-time 240 \
    -X POST "$CL/api/v1/networks/fabricx/$NETA_ID/nodes/$nid/join" \
    | jq '.status'
done

Why --max-time 240: on macOS Docker Desktop the first container start under a cold bind-mount cache can take 60–120 seconds. After the first component warms the cache, subsequent joins succeed in seconds. Retry individually on timeout.

Verify all 8 nodes are running:

curl -s -u "$AUTH" "$CL/api/v1/nodes?platform=FABRICX" \
  | jq '.items[] | {id, name, status}'

All should show "status": "RUNNING".

Step 6 — Create a namespace

curl -s -u "$AUTH" -X POST "$CL/api/v1/networks/fabricx/$NETA_ID/namespaces" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"token\",
    \"submitterOrgId\": $ORG1,
    \"waitForFinality\": true
  }"

Expected response:

{ "id": 17, "status": "committed", "txId": "fa5670f38f45..." }

See Namespaces for the namespace lifecycle and postgres layout.

Running a second network on the same host

Repeat steps 2–6 with the netB port band and name: "netB". All resources are independent; only ports must be unique.

Reusing organizations across networks

If Party1MSP's org and CAs already exist from network A, just reuse $ORG1..$ORG4 in network B's orderer group, committer, and network requests. You don't need new orgs.

Container name collisions

Container names derive from the node's name field (netA-orderer-p1-router, etc.). As long as network A and network B node names differ (netA-* vs netB-*), Docker runs both sets side-by-side.

Bind-mount directory collisions

Bind mounts are keyed by node name under chaindeploy/data/fabricx-orderers/<node-name>/ and chaindeploy/data/fabricx-committers/<node-name>/. Distinct node names → distinct directories.

Tearing down a network

The built-in delete doesn't purge Docker state. You need to clean up manually:

# 1. Delete via API (drops DB rows).
curl -s -u "$AUTH" -X DELETE "$CL/api/v1/networks/fabricx/$NETA_ID"
for nid in $NODE_IDS; do
  curl -s -u "$AUTH" -X DELETE "$CL/api/v1/nodes/$nid"
done
 
# 2. Remove containers.
docker ps -a --filter name=netA- -q | xargs -r docker rm -f
 
# 3. Remove bind mounts.
rm -rf chaindeploy/data/fabricx-orderers/netA-*
rm -rf chaindeploy/data/fabricx-committers/netA-*
 
# 4. Remove volumes if any.
docker volume prune -f

Skipping steps 2 or 3 will cause ABORTED_SIGNATURE_INVALID on the next rebuild, because committers resume from a stale ledger position against a freshly-regenerated genesis block.

Troubleshooting

Glossary

See also

• Overview
• Architecture
• Quickstart
• Namespaces
• Monitoring
• Certificate renewal
• Backup and restore
• Network Templates
• Troubleshooting