Cosmovisor Guide

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.

Setup

1. Download Cosmovisor

Using the command below, users can download the latest cosmovisor binary file. We recommend you to use the most recent version of cosmovisor. 

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

Please copy the downloaded cosmovisor binary using the command below.

sudo mv ~/go/bin/cosmovisor /usr/local/bin/cosmovisor

* If you are using go v1.18 or earlier, you will need to use go get, and you may want to run the command outside a project directory.

2. Setting up environmental variables

cosmovisor reads its configuration from environment variables:

  • DAEMON_HOME

    • This is the folder directory of the running chain.

    • export DAEMON_HOME=$HOME/.firmachain

  • DAEMON_NAME

    • This is the directory of the binary file once the chain starts running.

    • export DAEMON_NAME=firmachaind

  • DAEMON_ALLOW_DOWNLOAD_BINARIES (optional, default = false)

    • This setting asks whether you would automatically download the binary file.

    • Due to update issues, Cosmos does not recommend you true the AutoDownload. (Link)

  • DAEMON_RESTART_AFTER_UPGRADE (optional, default = true)

    • If you set the variable as true, the chain restarts using the new binary, post-upgrade.

    • If you set the variable as false, the chain must be restarted manually by the manager post-upgrade.

      * IMPORTANT : Restart will only happen after the upgrade and if any error occurs during the upgrade, the chain will not restart.

  • DAEMON_POLL_INTERVAL (optional, default = 300ms)

    • This is the length of the space to poll the upgrade plan file. (e.g. 1s).

    • The value can either be a number (in milliseconds) or a duration (e.g. 1s).

  • UNSAFE_SKIP_BACKUP (defaults to false)

    • If you set the variable as true, the upgrade will start without any data backup. If you wish to backup your data before upgrade, please set this variable as false or delete this settings category.

    • If you set the variable as false, it becomes easier to roll back and therefore, we recommend you use this feature.

  • DAEMON_PREUPGRADE_MAX_RETRIES (defaults to 0)

    • This option sets the number of pre upgrade call attempts.

    • If the pre upgrade call attempt reaches the set limit due to consistent failure, cosmovisor will fail to upgrade.

Following is a sample setting of the above variables. Options can be modified in ways that suits your purpose after reading the description of each variable mentioned above. DAEMON_HOME and DAEMON_NAME must be used as is. (Do not modify!)

echo "# [FirmaChain] Setup Cosmovisor" >> ~/.profile
echo "export DAEMON_NAME=firmachaind" >> ~/.profile
echo "export DAEMON_HOME=$HOME/.firmachain" >> ~/.profile
echo "export DAEMON_ALLOW_DOWNLOAD_BINARIES=false" >> ~/.profile
echo "export DAEMON_RESTART_AFTER_UPGRADE=true" >> ~/.profile
echo "export DAEMON_POLL_INTERVAL=300" >> ~/.profile
echo "export UNSAFE_SKIP_BACKUP=false" >> ~/.profile
echo "export DAEMON_PREUPGRADE_MAX_RETRIES=0" >> ~/.profile

The explanation above describes the option variables to run cosmovisor and in order to safely manage and use cosmovisor we recommend you add to the ~/.profile file.

source ~/.profile

3. Copying 'firmachaind' files in the proper folders

cosmovisor must be able to read and run the firmachain binary. Please execute the command provided below.

mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin
cp $(which firmachaind) $DAEMON_HOME/cosmovisor/genesis/bin/

:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

※ In case of 1.0.0 version.

  • Please execute the command below. If you don't execute this command, you can't run cosmovisor.

echo "{}" >> /home/firma/.firmachain/cosmovisor/current/upgrade-info.json

:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Whether you’ve properly configured the settings mentioned above can be determined using the command provided below.

$ cosmovisor run version
cosmovisor version: 'your install version'
7:41AM INF running app args=["version"] module=cosmovisor path=/home/firma/.firmachain/cosmovisor/genesis/bin/firmachaind
0.3.3

In order to run with cosmovisor, you must quite the original firmachaind process.

ps -ef | grep firmachaind
pkill <process id>

Finally, start cosmovisor

$ cosmovisor run start
7:44AM INF running app args=["start"] module=cosmovisor path=/home/firma/.firmachain/cosmovisor/genesis/bin/firmachaind
7:44AM INF starting ABCI with Tendermint
7:44AM INF Starting multiAppConn service impl=multiAppConn module=proxy
7:44AM INF Starting localClient service connection=query impl=localClient module=abci-client
7:44AM INF Starting localClient service connection=snapshot impl=localClient module=abci-client
7:44AM INF Starting localClient service connection=mempool impl=localClient module=abci-client
7:44AM INF Starting localClient service connection=consensus impl=localClient module=abci-client
7:44AM INF Starting EventBus service impl=EventBus module=events
7:44AM INF Starting PubSub service impl=PubSub module=pubsub
7:44AM INF Starting IndexerService service impl=IndexerService module=txindex
7:44AM INF ABCI Handshake App Info hash= height=0 module=consensus protocol-version=0 software-version=0.3.3
7:44AM INF ABCI Replay Blocks appHeight=0 module=consensus stateHeight=0 storeHeight=0
7:44AM INF asserting crisis invariants inv=0/11 module=x/crisis name=gov/module-account
7:44AM INF asserting crisis invariants inv=1/11 module=x/crisis name=distribution/nonnegative-outstanding
7:44AM INF asserting crisis invariants inv=2/11 module=x/crisis name=distribution/can-withdraw
7:44AM INF asserting crisis invariants inv=3/11 module=x/crisis name=distribution/reference-count
7:44AM INF asserting crisis invariants inv=4/11 module=x/crisis name=distribution/module-account
7:44AM INF asserting crisis invariants inv=5/11 module=x/crisis name=bank/nonnegative-outstanding
7:44AM INF asserting crisis invariants inv=6/11 module=x/crisis name=bank/total-supply
7:44AM INF asserting crisis invariants inv=7/11 module=x/crisis name=staking/module-accounts
7:44AM INF asserting crisis invariants inv=8/11 module=x/crisis name=staking/nonnegative-power
7:44AM INF asserting crisis invariants inv=9/11 module=x/crisis name=staking/positive-delegation
7:44AM INF asserting crisis invariants inv=10/11 module=x/crisis name=staking/delegator-shares
...
12:55PM INF ABCI Replay Blocks appHeight=1 module=consensus stateHeight=1 storeHeight=1

4. Registering Cosmovisor to the system (Optional)

If your server went down and you have to restart, you can let it restart automatically by registering the service. Please follow the example provided below.

sudo tee /etc/systemd/system/firmachaind.service > /dev/null <<EOF  
[Unit]
Description=Firmachain Node
After=network-online.target

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

Environment="DAEMON_HOME=$HOME/.firmachain"
Environment="DAEMON_NAME=firmachaind"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="UNSAFE_SKIP_BACKUP=false"

[Install]
WantedBy=multi-user.target
EOF

Once you’ve created the system file, please register the file to the system by using the command provided below.

sudo systemctl daemon-reload

Finally, restart.

sudo systemctl restart firmachaind
PreviousUpgradeNextCosmovisor Example

Last updated