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 archwayd 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.

How does cosmovisor work?

Cosmovisor is designed to be used as an abstract interface for the Cosmos SDK chain, for example Archway. Some key takeaways about Cosmovisor:

• it passes arguments to archwayd (which is configured by DAEMON_NAME env variable).
• It manages archwayd by restarting and upgrading if needed.
• It is configured using environment variables, not positional arguments.
• Running cosmovisor run arg1 arg2 .... runs archwayd arg1 arg2 ...
• All arguments passed to cosmovisor run are passed to the application binary, as a subprocess. As cosmovisor returns /dev/stdout and /dev/stderr of the subprocess as its own, cosmovisor run cannot accept any command-line arguments other than those available to archwayd.

Make sure to check the cosmovisor documentation for a comprehensive guide on how to use Cosmovisor.

Environment variables

Cosmovisor reads its configuration from environment variables:

• DAEMON_HOME is the location where the cosmovisor/ directory is kept that contains the genesis binary, the upgrade binaries, and any additional auxiliary files associated with each binary.
• DAEMON_NAME is the name of the binary itself.
• DAEMON_ALLOW_DOWNLOAD_BINARIES (optional), if set to true, will enable auto-downloading of new binaries. By default, cosmovisor will not auto-download new binaries. If running a validator, it is recommended to set this variable to
• DAEMON_RESTART_AFTER_UPGRADE (optional, default = true), if true, restarts the subprocess with the same command-line arguments and flags (but with the new binary) after a successful upgrade. Otherwise (false), cosmovisor stops running after an upgrade and requires the system administrator to manually restart it. Note restart is only after the upgrade and does not auto-restart the subprocess after an error occurs.

Install cosmovisor

First, make sure to have looked into the prerequisites, installation, and keys sections.

Install Cosmovisor with:

go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@latest

and check that the installation has been successful with:

cosmovisor

Configure cosmovisor

First, create the required directories by executing the following commands:

mkdir -p "${HOME}"/.archway/cosmovisor/genesis/binmkdir "${HOME}"/.archway/cosmovisor/upgrades

Then copy the archwayd binary to the genesis/bin folder:

cp "${GOPATH}"/bin/archwayd "${HOME}"/.archway/cosmovisor/genesis/bin

Add the necessary environment variables, for example by adding these variables to the profile that will be running Cosmovisor. You can edit the ~/.profile file by adding the following content:

export DAEMON_HOME="${HOME}"/.archwayexport DAEMON_RESTART_AFTER_UPGRADE=trueexport DAEMON_ALLOW_DOWNLOAD_BINARIES=falseexport DAEMON_NAME=archwaydexport UNSAFE_SKIP_BACKUP=true

Run cosmovisor as a service

Before running Cosmovisor, you should make sure to have initialized your archway node and looked into the joining a network section to download the genesis file, the snapshot and set up the persistent peers.

You can create a service file with:

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

and add the following content by making sure to change the <your-user>, <path-to-cosmovisor> and <path-to-archway> with your values:

[Unit]Description=cosmovisorAfter=network-online.target[Service]User=<your-user>ExecStart=/<path-to-cosmovisor>/cosmovisor start --x-crisis-skip-assert-invariantsRestart=alwaysRestartSec=3LimitNOFILE=4096Environment="DAEMON_NAME=archwayd"Environment="DAEMON_HOME=/<path-to-archway>/.archway"Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"Environment="DAEMON_RESTART_AFTER_UPGRADE=true"Environment="DAEMON_LOG_BUFFER_SIZE=512"Environment="UNSAFE_SKIP_BACKUP=true"[Install]WantedBy=multi-user.target

You can now reload the systemctl daemon:

sudo -S systemctl daemon-reload

and enable Cosmovisor as a service:

sudo -S systemctl enable cosmovisor

You can now start Cosmovisor by executing:

sudo systemctl start cosmovisor

Make sure to check that the service is running by executing:

sudo systemctl status cosmovisor