Cosmovisor

Nolus upgrades its node software through on-chain governance. A passed upgrade proposal names the upgrade, for example v0.8.6, together with a block height, and when the chain reaches that height every node stops and must restart with the new binary. Cosmovisor is a small process manager from the Cosmos SDK that watches for that halt and switches binaries for you. It is optional, and without it you replace the binary and restart the node by hand at the upgrade height.

Install Cosmovisor

Cosmovisor is distributed as a Go module, so installing it requires Go:

go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest

The binary lands in $(go env GOPATH)/bin, and the service below expects it in /usr/local/bin, so copy it there:

sudo install -m 0755 "$(go env GOPATH)/bin/cosmovisor" /usr/local/bin/cosmovisor

Set the environment variables

Cosmovisor finds the daemon through two environment variables, which you set in your shell:

export DAEMON_NAME=nolusd
export DAEMON_HOME=$HOME/.nolus

Add the same two lines to ~/.profile so that they survive a new shell.

Add the current binary

Cosmovisor keeps binaries under $DAEMON_HOME/cosmovisor, with the starting binary in genesis/bin, each upgrade in upgrades/<upgrade name>/bin and a current link to the active one. Initialize this layout with the release binary you downloaded and verified:

cosmovisor init ./nolusd

When you start from a snapshot, the starting binary must be the version the chain runs today, v0.8.6, and not the version the chain launched with.

Create the systemd service

Create /etc/systemd/system/cosmovisor.service with the following content:

[Unit]
Description=Nolus node (cosmovisor)
After=network-online.target

[Service]
User=<user>
ExecStart=/usr/local/bin/cosmovisor run start
Restart=always
RestartSec=3
LimitNOFILE=65535
Environment="DAEMON_NAME=nolusd"
Environment="DAEMON_HOME=/home/<user>/.nolus"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="UNSAFE_SKIP_BACKUP=false"

[Install]
WantedBy=multi-user.target

Replace <user> in both places with the user that runs the node. Then load and enable the service with sudo systemctl daemon-reload && sudo systemctl enable cosmovisor, and start it as described in Run the node.

Prepare for an upgrade

Getting ready for an upgrade starts with watching for a scheduled plan:

nolusd q upgrade plan

Once a plan appears, there are two ways to get the new binary in place before its height.

Register the binary manually

Registering the binary yourself is the recommended option for validators. Download and verify the new release as in Install nolusd, then register it under the plan's upgrade name:

cosmovisor add-upgrade <upgrade name> ./nolusd

Replace <upgrade name> with the name that the upgrade plan gives.

Download the binary automatically

Nolus upgrade plans carry a download map in their info field with the same content as the release's <version>_binaries.json, which for v0.8.6 reads as follows:

{"binaries": {"linux/amd64": "https://github.com/nolus-protocol/nolus-core/releases/download/v0.8.6/nolusd?checksum=sha256:5aecd3328134db251f88eda791f8fe84ba619f5ec85cb383ca0c836a84c17a60"}}

When you set DAEMON_ALLOW_DOWNLOAD_BINARIES=true, Cosmovisor downloads the binary at the upgrade height and checks it against that sha256. The Cosmos SDK documents automatic download as intended for full nodes rather than validators.