Migration Guide

How to migrate your existing blockchain infrastructure to ChainLaunch from manual setups, Docker Compose, Kubernetes, or other platforms.

Migration Paths

Migrate from Docker Compose

This is the most common migration path — you have a Fabric or Besu network running in Docker containers managed by docker-compose.yml.

Step 1: Install ChainLaunch

curl -fsSL https://chainlaunch.dev/deploy.sh | bash

Step 2: Document Your Current Network

Before migrating, inventory your existing setup:

# List running blockchain containers
docker ps --filter "label=org.hyperledger" --format "table {{.Names}}\t{{.Image}}\t{{.Ports}}"
 
# For Fabric — find your crypto material
ls crypto-config/  # or organizations/ depending on your setup
 
# For Besu — find your genesis and keys
cat genesis.json
ls keys/

Record:

• Organization names and MSP IDs (Fabric)
• Number of peers, orderers, CAs per org
• Channel names and member orgs
• Validator addresses (Besu)
• Chain ID and consensus settings (Besu)

Step 3: Create Organizations in ChainLaunch

For each organization in your existing network:

chainlaunch fabric org create \
  --name Org1 \
  --msp-id Org1MSP \
  --provider-id 1

Step 4: Import Crypto Material

ChainLaunch can import existing keys and certificates:

# Import an existing CA certificate + key
curl -X POST http://localhost:8100/api/v1/keys/import \
  -H "Content-Type: application/json" \
  -d '{
    "name": "org1-ca-key",
    "type": "CA",
    "organizationId": 1,
    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  }'

Repeat for each organization's CA, TLS, and identity keys.

Step 5: Create Nodes

Create nodes in ChainLaunch that correspond to your existing containers:

chainlaunch fabric peer create \
  --name peer0-org1 \
  --org-id 1 \
  --msp-id Org1MSP

Step 6: Stop Old Containers and Start New Ones

# Stop the old Docker Compose setup
docker-compose down
 
# Start nodes via ChainLaunch (slug or numeric ID)
chainlaunch nodes start peer0-org1

Step 7: Verify

# Check all peer / orderer / besu nodes
chainlaunch fabric peer list
chainlaunch fabric orderer list
chainlaunch besu list
 
# Check channels (Fabric)
chainlaunch networks fabric list

Migrate from Hyperledger Bevel

Bevel uses Helm charts on Kubernetes. The key difference is that Bevel manages crypto material in Vault and network config in Helm values files.

Step 1: Export from Bevel

# Export crypto material from Vault
vault kv get -format=json secret/crypto/peerOrganizations/org1/peers/peer0/msp > peer0-msp.json
 
# Export channel config
kubectl exec -it peer0-org1 -- peer channel fetch config -o orderer:7050 -c mychannel
 
# Export genesis block (Besu)
kubectl exec -it validator-0 -- cat /data/genesis.json > genesis.json

Step 2: Install ChainLaunch and Import

Follow Steps 1-5 from the Docker Compose migration above, using the exported crypto material.

Step 3: Recreate Network Topology

Use ChainLaunch's testnet command to recreate the network structure, then import the existing ledger data:

# Create the network structure
chainlaunch testnet fabric \
  --name migrated-network \
  --org "Org1MSP,Org2MSP" \
  --peerOrgs "Org1MSP,Org2MSP" \
  --ordererOrgs "Org1MSP" \
  --channels mychannel \
  --peerCounts "Org1MSP=2,Org2MSP=1" \
  --ordererCounts "Org1MSP=3"

Migrate Between ChainLaunch Instances

The easiest migration — use backup/restore or network templates.

Option A: Backup and Restore

# On the source instance: create a backup
chainlaunch backups create --target-id 1
 
# On the target instance: restore
chainlaunch backup restore \
  --s3-endpoint="..." \
  --bucket-name="..." \
  --output="$HOME/chainlaunch-restore"

See Restore from Backup for the full procedure.

Option B: Network Templates (Pro)

Export a network as a portable template and import it on another instance:

# Export
chainlaunch networks fabric template export --network-id 1 --out my-network-template.json
 
# Validate on the target
chainlaunch networks fabric template validate --file my-network-template.json
 
# Import
chainlaunch networks fabric template import --file my-network-template.json

Templates include variable placeholders (${orgName.mspId}) that are resolved during import, making them portable across environments.

Post-Migration Checklist

• All organizations created with correct MSP IDs
• All nodes running and healthy
• Channels/networks visible in the dashboard
• Chaincode/smart contracts deployed and queryable
• Monitoring configured for the new nodes
• Backup schedule configured
• Old infrastructure decommissioned
• DNS records updated (if applicable)
• Team members have access (RBAC configured)

Troubleshooting

Ledger data not syncing

If peers can't sync existing ledger data after migration:

• Ensure the genesis block matches the original network
• Check that the MSP IDs match exactly (case-sensitive)
• Verify the orderer TLS certificates are correct

Certificate mismatch

If nodes can't communicate after migration:

• Re-export and re-import the TLS certificates
• Ensure the CA chain is complete (root CA + intermediate CAs)
• Check that certificate subject names match the node hostnames

Next Steps

• Quick Start if starting fresh instead of migrating
• Backups to protect your migrated network
• Network Templates for portable network definitions