What is cosmovisor?

Cosmovisor is a powerful utility for managing the binary version of Cosmos SDK-based chains. Its primary function is to enable seamless binary upgrades without requiring a full node restart or manual intervention. In essence, Cosmovisor provides for automated processes to handle upgrades, reducing downtime or manual intervention.

Even when automatic upgrades are not enabled, Cosmovisor remains a valuable tool for managing different versions of the terpd binary. It simplifies the process of managing different versions of the binary by automatically switching to the appropriate binary version based on the block height. This helps reduce potential errors or missed upgrades during the manual process, allowing validators to maintain their nodes with greater ease and accuracy.

While Cosmovisor can also automate the process of downloading and installing new binaries, it's important to note that node operators bear the responsibility of ensuring the binaries they are running are trustworthy. Therefore, even when using Cosmovisor, it is recommended for operators to remain vigilant of upgrade proposals and verify new binaries independently.

In cases where a node operator prefers or requires a greater degree of control, manual upgrades are preferable.

Install

To install the latest version of cosmovisor, run the following command:

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

Decide on auto-downloads explicitly: DAEMON_ALLOW_DOWNLOAD_BINARIES=false means you place each upgrade binary by hand (safest); true lets Cosmovisor fetch the binary named in the upgrade plan. Either way, verify upgrade binaries against the releases bucket and watch proposals — see Chain upgrades.

Your installation can be confirmed with:

which cosmovisor

This will return something like:

/home/<your-user>/go/bin/cosmovisor

Add environment variables to your shell

In the .profile file, usually located at ~/.profile, add:

export DAEMON_NAME=terpd
export DAEMON_HOME=$HOME/.terpd

Then source your profile to have access to these variables:

source ~/.profile

You can confirm success like so:

echo $DAEMON_NAME

It should return terpd.

Set up folder structure

Cosmovisor expects a certain folder structure:

.
├── current -> genesis or upgrades/<name>
├── genesis
│   └── bin
│       └── $DAEMON_NAME
└── upgrades
    └── <name>
        └── bin
            └── $DAEMON_NAME

Don't worry about current - that is simply a symlink used by Cosmovisor. The other folders will need setting up, but this is easy:

mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin && mkdir -p $DAEMON_HOME/cosmovisor/upgrades

Set up genesis binary

Cosmovisor needs to know which binary to use at genesis. We put this in $DAEMON_HOME/cosmovisor/genesis/bin.

First, find the location of the binary you want to use:

which terpd

Then use the path returned to copy it to the directory Cosmovisor expects. Let's assume the previous command returned /home/your-user/go/bin/terpd:

cp $HOME/go/bin/terpd $DAEMON_HOME/cosmovisor/genesis/bin

Cosmovisor init

cosmovisor init creates the directory layout and copies the current binary into place:

cosmovisor init $HOME/go/bin/terpd
tree $DAEMON_HOME/cosmovisor
# cosmovisor/
# genesis/bin/terpd      <- current binary
# upgrades/<name>/bin/   <- place each upgrade binary here (unless auto-download)

Set up service

Commands sent to Cosmovisor are sent to the underlying binary. For example, cosmovisor version is the same as typing terpd version.

Nevertheless, just as we would manage terpd using a process manager, we would like to make sure Cosmovisor is automatically restarted if something happens, for example an error or reboot.

First, create the service file:

sudo nano /etc/systemd/system/terpd.service

Change the contents of the below to match your setup - cosmovisor is likely at ~/go/bin/cosmovisor regardless of which installation path you took above, but it's worth checking.

Note cosmovisor run start is only for the latest versions of cosmovisor. For earlier versions that line should be:

ExecStart=/home/<your-user>/go/bin/cosmovisor start

[Unit]
Description=Terp Network  (cosmovisor)
After=network-online.target
 
[Service]
User=<your-user>
ExecStart=$HOME/go/bin/cosmovisor run start
Restart=always
RestartSec=3
LimitNOFILE=65535
Environment="DAEMON_NAME=$DAEMON_NAME"
Environment="DAEMON_HOME=$DAEMON_HOME"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_LOG_BUFFER_SIZE=512"
 
[Install]
WantedBy=multi-user.target

Sync before starting

Restore a snapshot or state-sync into $DAEMON_HOME before enabling the service — Cosmovisor just supervises terpd start, so the data directory must already be synced (or syncing via a process Cosmovisor manages from block 1).

Start Cosmovisor

Finally, enable the service and start it.

sudo -S systemctl daemon-reload
sudo -S systemctl enable terpd
# check config one last time before starting!
sudo systemctl start terpd

Check it is running using:

sudo systemctl status terpd

If you need to monitor the service after launch, you can view the logs using:

journalctl -fu terpd