Skip to main content

Migration Guide

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

Migration Paths​

FromComplexityWhat migratesWhat doesn't
Manual Docker/Docker ComposeLowNetwork config, keys, ledger dataDocker Compose files (replaced by ChainLaunch)
Hyperledger BevelMediumNetwork topology, crypto material, channelsHelm charts, K8s manifests
Kubernetes (manual)MediumNetwork config, persistent volumesK8s manifests, operators
Kaleido / ChainstackMedium-HighNetwork config, keys (if exportable)Platform-specific features
Another ChainLaunch instanceLowEverything via backup/restore or templatesInstance-specific settings

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:

# Via API
curl -X POST http://localhost:8100/api/v1/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Org1",
    "mspId": "Org1MSP",
    "description": "Migrated from Docker Compose"
  }'

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:

curl -X POST http://localhost:8100/api/v1/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "name": "peer0-org1",
    "platform": "FABRIC",
    "nodeType": "FABRIC_PEER",
    "organizationId": 1
  }'

Step 6: Stop Old Containers and Start New Ones​

# Stop the old Docker Compose setup
docker-compose down

# Start nodes via ChainLaunch
curl -X POST http://localhost:8100/api/v1/nodes/{nodeId}/start

Step 7: Verify​

# Check all nodes are running
curl http://localhost:8100/api/v1/nodes | jq '.[].status'

# Check channels (Fabric)
curl http://localhost:8100/api/v1/networks | jq '.[].name'

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
curl -X POST http://localhost:8100/api/v1/backups \
  -H "Content-Type: application/json" \
  -d '{"targetId": 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
curl http://localhost:8100/api/v1/networks/templates/export/1 > my-network-template.json

# Validate on the target
curl -X POST http://localhost:8100/api/v1/networks/templates/validate \
  -H "Content-Type: application/json" \
  -d @my-network-template.json

# Import
curl -X POST http://localhost:8100/api/v1/networks/templates/import \
  -H "Content-Type: application/json" \
  -d @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​