Skip to main content

Automated Upgrades

We highly recommend validators use Cosmovisor to run their nodes. This will make low-downtime upgrades smoother, as validators don't have to manually upgrade binaries during the upgrade. Instead, users can pre-install new binaries and Cosmovisor will automatically update them based on on-chain Software Upgrade proposals.

cosmovisor is a small process manager for Cosmos SDK application binaries that monitors the governance module for incoming chain upgrade proposals. If it sees a proposal that gets approved, cosmovisor can automatically download the new binary, stop the current binary, switch from the old binary to the new one, and finally restart the node with the new binary.

Prerequisites​

1. Setup Cosmovisor​

Set up the Cosmovisor environment variables. We recommend setting these in your .profile so it is automatically set in every session.

echo "# Setup Cosmovisor" >> ~/.profile
echo "export DAEMON_NAME=" >> ~/.profile
echo "export DAEMON_HOME=$HOME/.dep" >> ~/.profile
source ~/.profile

After this, you must make the necessary folders for cosmosvisor in your DAEMON_HOME directory (~/.dep) and copy over the current binary.

mkdir -p ~/.dep/cosmovisor
mkdir -p ~/.dep/cosmovisor/genesis
mkdir -p ~/.dep/cosmovisor/genesis/bin
mkdir -p ~/.dep/cosmovisor/upgrades

cp $GOPATH/bin/dep ~/.dep/cosmovisor/genesis/bin

To check that you did this correctly, ensure your versions of cosmovisor and dep are the same:

cosmovisor run version
dep version

2. Download the DEP release​

Manual Download​

Cosmovisor will continually poll the $DAEMON_HOME/data/upgrade-info.json for new upgrade instructions. When an upgrade is released, node operators need to:

  1. Download (NOT INSTALL) the binary for the new release
  2. Place it under $DAEMON_HOME/cosmovisor/upgrades/<name>/bin, where <name> is the URI-encoded name of the upgrade as specified in the Software Upgrade Plan.

Example: for a Plan with name v3.0.0 with the following upgrade-info.json:

Your cosmovisor/ directory should look like this:

cosmovisor/
├── current/   # either genesis or upgrades/<name>
├── genesis
│   └── bin
│       └── dep
└── upgrades
    └── v3.0.0
        ├── bin
        │   └── dep
        └── upgrade-info.json

Automatic Download​

danger

NOTE: Auto-download doesn't verify in advance if a binary is available. If there will be any issue with downloading a binary, cosmovisor will stop and won't restart and the chain (which could lead it to a halt).

It is possible to have Cosmovisor automatically download the new binary. Validators can use the automatic download option to prevent unnecessary downtime during the upgrade process. This option will automatically restart the chain with the upgrade binary once the chain has halted at the proposed upgrade-height. The major benefit of this option is that validators can prepare the upgrade binary in advance and then relax at the time of the upgrade.

To set the auto-download use set the following environment variable:

echo "export DAEMON_ALLOW_DOWNLOAD_BINARIES=true" >> ~/.profile

3. Start your node​

Now that everything is set up and ready to go, you can start your node.

cosmovisor run start

You will need some way to keep the process always running. If you're on linux, you can do this by creating a service.

sudo tee /etc/systemd/system/dep.service > /dev/null <<EOF
[Unit]
Description=DEP Daemon
After=network-online.target

[Service]
User=$USER
ExecStart=$(which cosmovisor) start
Restart=always
RestartSec=3
LimitNOFILE=infinity

Environment="DAEMON_HOME=$HOME/.dep"
Environment="DAEMON_NAME=dep"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"

[Install]
WantedBy=multi-user.target
EOF

Then update and start the node

sudo -S systemctl daemon-reload
sudo -S systemctl enable dep
sudo -S systemctl start dep

You can check the status with:

systemctl status dep