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, use the built-in updater:

# Latest release
GITHUB_TOKEN=ghp_... chainlaunch update
 
# Specific tag
GITHUB_TOKEN=ghp_... chainlaunch update --tag v1.4.2

The command downloads the matching Pro binary from the private releases repo and installs it into $HOME/.chainlaunch-pro (override with --install-dir).

Version Compatibility

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