Fabric-X Quickstart

Provision a complete 4-party Fabric-X network in one click using the ChainLaunch web UI. This is the fastest path from zero to a running network — useful for evaluation, local development, and demos.

What you'll get

After the quickstart completes, you'll have:

1 organization (AcmeMSP) shared across all 4 parties — this is the default Single MSP mode. Endorsements collapse to one signer, which is the easiest setup for FSC sample apps and local development. Switch to Multi-MSP mode if you want 4 distinct MSPs, the production-shape Arma BFT topology.
4 orderer groups (16 containers: router, batcher, consenter, assembler × 4).
1 shared committer in single-MSP mode (5 containers: sidecar, coordinator, validator, verifier, query-service). Multi-MSP mode creates one committer per party (20 containers total).
1 shared postgres service (1 container, 4 databases — one per party).
1 Fabric-X network using Arma consensus on the arma channel.
All nodes joined and running — ready to accept namespace creation and token-sdk-x transactions.

Totals on one host:

Mode	Total containers
Single MSP	22 (16 orderer + 5 committer + 1 postgres)
Multi-MSP	37 (16 orderer + 20 committer + 1 postgres)

Prerequisites

ChainLaunch server running (default: http://localhost:8100).
Docker Desktop (macOS/Windows) or Docker Engine (Linux) — running and reachable.
Sufficient host resources: ~8 GB free RAM, ~10 GB disk.
Admin credentials. If you used deploy.sh, the password is in ~/.chainlaunch/credentials.txt. If you installed manually, it's whatever you exported as CHAINLAUNCH_PASSWORD on first start. The examples below use admin:admin123 as a placeholder — substitute your real password.

macOS / Windows only — enable local-dev rewriting

On Docker Desktop, containers reach the host via host.docker.internal rather than a direct IP. The quickstart form has a Local development mode checkbox — enable it on macOS/Windows. This rewrites, per-network:

container-to-container addresses → host.docker.internal
host-to-container dials → 127.0.0.1
gRPC TLS ServerName → localhost (so certificate SANs still validate)

Alternatively, set this env var on the ChainLaunch server process to enable it globally for every FabricX network (the per-network flag still wins):

export CHAINLAUNCH_FABRICX_LOCAL_DEV=true

On Linux with native Docker, leave both unset — external IPs are directly reachable.

Run the quickstart

Option A — Web UI

Open ChainLaunch in your browser (default: http://localhost:8100).
Log in with your admin credentials.
Navigate to Networks → Fabric-X → Quick-start (direct URL: /networks/fabricx/quickstart).
Review the defaults — network name, party count, port base.
Click Start.

The wizard runs a 5-phase provisioning flow and streams progress as each step completes.

Option B — CLI

The same flow is also available as a single CLI command, useful for CI and scripted environments:

# macOS / Windows only:
export CHAINLAUNCH_FABRICX_LOCAL_DEV=true

chainlaunch fabricx quickstart \
  --network-name my-fabricx \
  --parties 4 \
  --mode single                   # or --mode multi for distinct MSPs per party

Common flags:

Flag	Purpose	Default
`--network-name`	Network name.	`fabricx-quickstart`
`--parties`	Number of parties (1–10).	`4`
`--mode`	`single` (one shared MSP) or `multi` (one MSP per party).	`single`
`--single-msp`	MSPID used by `--mode=single`.	`AcmeMSP`
`--base-port`	First port in the reserved range.	See `--help`
`--postgres-port`	Host port for the shared Postgres container.	`15432`
`--namespace`	Namespace created as a post-provisioning health check (empty to skip).	`quickstart`
`--clean`	Wipe any prior bundle with this network name before provisioning.	`false`

Run chainlaunch fabricx quickstart --help for the full list (timeouts, retries, data path).

What happens under the hood

The quickstart runs the following phases sequentially. Each is idempotent — if an organization or node with the target name already exists, the wizard reuses it.

Phase	Action
1. Organizations	Single-MSP mode creates one `AcmeMSP` org reused by every party; multi-MSP creates `Party{N}MSP` per party. Each call falls back to the platform's default key provider when no `providerId` is supplied.
2. Postgres service	Provision the shared postgres service via `POST /services/postgres` and start it on the host port shown in the wizard (default `15432`).
3. Per-party databases	`POST /services/{id}/postgres/databases` with one entry per party (`party1_fabricx`, etc.). Idempotent — repeat invocations no-op.
4. Orderer groups	Create a FabricX orderer node-group per party via `POST /node-groups` then `/init`. Stage 1 only — certs are generated, containers are not started yet.
5. Committer	Single-MSP mode creates one shared committer node-group + node that all parties join; multi-MSP creates one committer per party. Stage 1 only.
6. Network	`POST /networks/fabricx` with all orgs + node pairs. This generates the Arma genesis block.
7. Join	For each orderer-group + the shared committer, call the join endpoint. This writes the genesis into the bind mount and starts the containers.

Containers only start during phase 5 — this is the two-stage lifecycle that Fabric-X uses so orderer groups and committers have the network's genesis block before they boot.

Expected timing

On a typical developer laptop:

Phases 1–4: seconds.
Phase 5 (join): 60–180 seconds, dominated by Docker pulling images and warming bind-mount caches on the first container. Subsequent nodes on the same host complete in seconds once the cache is warm.

The wizard uses a 240-second per-node timeout for join — safe for cold macOS Docker Desktop. If you see a timeout on the first node, retry that node individually; the cache is already warm from the partial attempt.

Verify the network

Once the wizard reports Ready, check:

All nodes running

Navigate to Nodes and filter by platform FABRICX. All 8 nodes should show RUNNING.

Or via API:

curl -s -u admin:admin123 http://localhost:8100/api/v1/nodes?platform=FABRICX \
  | jq '.items[] | {name, status}'

Network visible

Navigate to Networks. The newly-created fabricx-quickstart (or whatever you named it) should appear with status genesis_block_created (the live state once join completes — the network row's status field doesn't transition to ACTIVE; container readiness is reported on the node rows instead).

Create a test namespace

From the network detail page, click Create namespace and submit a name like test. A successful response includes a txId and status: "committed".

Behind the scenes, this sends a transaction through Party 1's router, which travels the full flow: batcher → Arma consensus → assembler → sidecar → commit → postgres table ns_test.

See Namespaces for more.

After the quickstart

Build an application against any party's router and query-service using token-sdk-x.
Inspect blocks and transactions via the built-in explorer at the network detail page.
Export the network as a template for reproducible provisioning — see Network Templates.

When to use the manual flow instead

The quickstart is opinionated — 4 parties, auto-allocated ports, sensible defaults. Use the manual creation guide when you need:

A different party count (1–10 supported).
Pinned port bands (required for running multiple Fabric-X networks on one host).
Custom organization names / MSP IDs.
Integration with existing orgs.
Programmatic provisioning from CI or IaC.

Troubleshooting

Symptom	Likely cause	Fix
Phase 5 times out	Cold Docker Desktop bind-mount cache	Retry the failing node individually; subsequent ones will be fast.
`dial ... context deadline exceeded` on namespace create	Local-dev mode not enabled (macOS/Windows)	Recreate the network with Local development mode checked, or set `CHAINLAUNCH_FABRICX_LOCAL_DEV=true` on the server.
`Port already in use` on join	Another Fabric-X network or service on the same host	Run the manual flow with a different port band.
`invalid mount config ... bind source path does not exist`	Docker Desktop cold cache	Same as first row — retry.

See Troubleshooting for general issues.

What you'll get​

Prerequisites​

macOS / Windows only — enable local-dev rewriting​

Run the quickstart​

Option A — Web UI​

Option B — CLI​

What happens under the hood​

Expected timing​

Verify the network​

All nodes running​

Network visible​

Create a test namespace​

After the quickstart​

When to use the manual flow instead​

Troubleshooting​

See also​