Releases management and upgrades

Intro

With this setup, you can handle Cosmos-style coordinated upgrades smoothly, without manual intervention at midnight or worrying about overwriting old binaries. This method is widely used in any environments because it makes upgrades predictable, reversible, and clean. Each release will be stored in its own subfolder under releases folder. Inside each release sub-folder, keep the binary under a bin directory for consistency.

Prepare the folders

Create sub-folder in the releases folder:

export VER=v6.0.5

mkdir -p $HOME/.some-chain/releases/$VER/bin

Move your compiled some-chain binary into the versioned folder:

mv $HOME/some-chain/build/some-chaind $HOME/.some-chain/releases/$VER/bin

Point the symlink `active-release`` to the current version’s folder:

ln -sfn $HOME/.some-chain/releases/$VER $HOME/.some-chain/active-release

This allows you to always run the active binary from:

$HOME/.some-chain/active-release/bin/some-chaind

How to upgrade

  • Create a new sub-folder for the new version inside releases.
  • Move the new binary there.
  • Update the active-release symlink to point to the new version.

Example for upgrading to v6.0.5:

mkdir -p $HOME/.some-chain/releases/v6.0.5/bin
mv $HOME/some-chain/build/some-chaind $HOME/.some-chain/releases/v6.0.5/bin
ln -sfn $HOME/.some-chain/releases/v6.0.5 $HOME/.some-chain/active-release

Why this structure is convenient

  • Clear organization: Each version has its own isolated folder.
  • Safe upgrades: You don’t overwrite old binaries; you simply add a new folder.
  • Easy rollbacks: To revert, just repoint the symlink back to a previous version.
  • Automation-friendly: Upgrade scripts only need to update the symlink, no need to rewrite paths.
  • Consistency: The binary path always stays the same (active-release/bin/celestia-appd), regardless of version.

Scheduled Upgrades at a Specific Block

In the Cosmos ecosystem, upgrades are often coordinated to happen at a specific block height. The node operator needs to stop the current binary and restart the node with a new binary exactly when the chain reaches that height.

With the release folder + symlink structure described earlier, this becomes simple and safe:

  1. Build or download the new binary in advance.
  2. Place it in a new versioned folder under ~/.some-chain/releases/.
  3. Don’t activate it yet — keep the active-release symlink pointing to the current version.

When the chain approaches the upgrade height, you can run a small script that:

  • Monitors the current block height.
  • At the target upgrade block, updates the active-release symlink to point to the new version.
  • Restarts the node service so it picks up the new binary.

⬇️ You can check out our Cosmos releated repo and get this script

Why This Works Well with the Folder Structure

  • No downtime preparation: You preload the new binary before the upgrade block.
  • Atomic switch: Updating the symlink is instantaneous.
  • Fast rollback: If the new binary crashes, simply repoint the symlink back to the previous version and restart the node.
  • Clean automation: The script always refers to active-release, so you don’t need to hardcode paths to different versions.
Previous
Grafana Monitoring