Skip to main content

Upgrade Guide

How to upgrade ChainLaunch to a new version without downtime for your blockchain networks.

Upgrading to v0.4.0? This release adds the Fabric-X subsystem. The change is purely additive — there are no breaking changes, no schema migrations beyond the auto-applied ones, and existing Fabric and Besu networks are unaffected. See the release notes for what's new.

Before You Upgrade​

  1. Read the release notes for breaking changes
  2. Back up your database and data directory
  3. Back up your blockchain data using Backups
# Back up the database
cp /var/lib/chainlaunch/chainlaunch.db /var/lib/chainlaunch/chainlaunch.db.bak

# Back up the data directory
tar czf chainlaunch-data-backup.tar.gz /var/lib/chainlaunch/

Upgrade via Install Script​

The simplest method — the install script detects the existing installation and upgrades in place:

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

This will:

  1. Detect the running ChainLaunch version
  2. Download the latest binary
  3. Replace the old binary
  4. Restart the service (if running as systemd)

Upgrade Manually​

Step 1: Download the New Binary​

export CHAINLAUNCH_VERSION=$(curl -s https://api.github.com/repos/LF-Decentralized-Trust-labs/chaindeploy/releases/latest | grep tag_name | cut -d '"' -f 4)

# Linux
curl -L -o chainlaunch "https://github.com/LF-Decentralized-Trust-labs/chaindeploy/releases/download/${CHAINLAUNCH_VERSION}/chainlaunch-linux-amd64"
chmod +x chainlaunch

# macOS (Apple Silicon)
curl -L -o chainlaunch "https://github.com/LF-Decentralized-Trust-labs/chaindeploy/releases/download/${CHAINLAUNCH_VERSION}/chainlaunch-darwin-arm64"
chmod +x chainlaunch

Step 2: Stop ChainLaunch​

sudo systemctl stop chainlaunch
# Or if running manually: kill the process

Your blockchain nodes (Docker containers) continue running — stopping ChainLaunch only stops the management plane.

Step 3: Replace the Binary​

sudo mv chainlaunch /usr/local/bin/chainlaunch

Step 4: Start ChainLaunch​

sudo systemctl start chainlaunch

Step 5: Verify​

chainlaunch version
# Should show the new version

curl http://localhost:8100/api/v1/health
# Should return healthy

Database Migrations​

ChainLaunch runs database migrations automatically on startup. If a new version includes schema changes, they are applied when the service starts.

If you need to run migrations manually:

chainlaunch migrate --db=/var/lib/chainlaunch/chainlaunch.db

Rollback​

If something goes wrong:

# Stop ChainLaunch
sudo systemctl stop chainlaunch

# Restore the old binary (keep a copy before upgrading)
sudo cp /usr/local/bin/chainlaunch.bak /usr/local/bin/chainlaunch

# Restore the database backup
cp /var/lib/chainlaunch/chainlaunch.db.bak /var/lib/chainlaunch/chainlaunch.db

# Start ChainLaunch
sudo systemctl start chainlaunch

Upgrading ChainLaunch Pro​

For Pro installations, the upgrade process is the same but uses the Pro binary:

# Download from the private releases repo (requires GitHub access)
curl -L -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -o chainlaunch \
  "https://github.com/chainlaunch/chainlaunch-pro-releases/releases/download/${VERSION}/chainlaunch-pro-linux-amd64"

Version Compatibility​

ChainLaunchFabricBesuGo
0.x2.5.x24.x1.23

ChainLaunch is backwards-compatible with networks created by older versions. You do not need to recreate your networks after upgrading.

Next Steps​

  • Backups to set up automated backups before upgrading
  • Troubleshooting if you encounter issues after upgrading