Skip to main content
Validators
Setting up Zetavisor

Setting up ZetaVisor

ZetaVisor is an optional process supervisor for ZetaChain. It is a wrapper around the zetacored binary that allows for automatic restarts automatic upgrades of the ZetaChain binary. It is a fork of the CosmosVisor tool.

You can use a prebuilt zetavisor binary or build it yourself from source.

Installing ZetaVisor​

Building From Source​

You need to have Go 1.19 and other dependencies first but those are outside the scope of this document. If you are uncomfortable building the binary from source code we recommend using a prebuilt binary as shown in the next step.

You can build from source by cloning the repository and running the following commands.

git clone https://github.com/zeta-chain/cosmos-sdk
cd cosmos-sdk/
git checkout zetavisor-v0.1.5
cd cosmovisor
make zetavisor
mv $GOPATH/bin/zetavisor /usr/local/bin/zetavisor

Download Zetavisor Binary​

Download the Binary for your system architecture from the following links and place it in your $PATH amd64: https://zetachain-external-files.s3.amazonaws.com/binaries/zetavisor/latest/zetavisor-amd64 arm64: https://zetachain-external-files.s3.amazonaws.com/binaries/zetavisor/latest/zetavisor-arm64

This example assumes you are using amd64 architecture. If you are using arm64 replace amd64 with arm64 in the commands below.

wget https://zetachain-external-files.s3.amazonaws.com/binaries/zetavisor/latest/zetavisor-amd64
mv zetavisor-amd64 /usr/local/bin/zetavisor

Setting up ZetaVisor​

Create zetavisor Directories​

mkdir -p ~/.zetacored/config
mkdir -p ~/.zetacored/zetavisor/genesis/bin
mkdir -p ~/.zetacored/zetavisor/upgrades

Setup zetavisor systemd service​

In this example we'll run zetavisor as a systemd service. You can also run it as a docker container or as a standalone process. The environment variables are explained in the Environment Variables section at the end of this document.

Create a file at /etc/systemd/system/zetavisor.service with the following contents. Make sure to change the User and /home/zetachain/ fields to the user you want to run the service as.

[Unit]
Description=Zetavisor ZetaChain Service
After=multi-user.target
StartLimitIntervalSec=0
[Install]
WantedBy=multi-user.target
[Service]
WorkingDirectory=/home/zetachain/.zetacored/zetavisor
Environment="DAEMON_HOME=/home/zetachain/.zetacored"
Environment="DAEMON_NAME=zetacored"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_DATA_BACKUP_DIR=/home/zetachain/.zetacored"
Environment="CLIENT_DAEMON_NAME=zetaclientd"
Environment="CLIENT_SKIP_UPGRADE=false"
Environment="CLIENT_START_PROCESS=false"
Environment="UNSAFE_SKIP_BACKUP=true"
Type=simple
Restart=always
RestartSec=600
User=zetachain
LimitNOFILE=262144
ExecStart=zetavisor start --home /home/zetachain/.zetacored/ --log_format json  --moniker <YOUR_NODE_NAME_HERE>

Install the zetacored Binary​

Download zetacored Binary​

Download the latest zetacored binary for your system architecture from the following links and place it in the zetavisor/genesis/bin/ directory. This example assumes you are using ubuntu 22 on amd64 architecture. You may need to make adjustments for your system.

wget https://zetachain-external-files.s3.amazonaws.com/binaries/athens3/latest/zetacored-ubuntu-22-amd64
mv zetacored-ubuntu-22-amd64 ~/.zetacored/zetavisor/genesis/bin/zetacored
chmod +x ~/.zetacored/zetavisor/genesis/bin/zetacored

Install ZetaChain Configuration Files​

ZetaChain configuration files for the Athens3 Testnet can be downloaded from the Athens3 Github Repo

Install them as follows:

git clone https://github.com/zeta-chain/network-athens3
cp network-athens3/network_files/config/* ~/.zetacored/config/

Starting ZetaVisor​

State Sync​

You may choose to sync the state of your node from a snapshot. This will speed up the time it takes to sync your node. Instructions for syncing from a snapshot can be found here.

Start the zetavisor Service​

sudo systemctl daemon-reload
sudo systemctl enable zetavisor
sudo systemctl start zetavisor

Check the zetavisor Service Status​

sudo systemctl status zetavisor

Check the zetavisor Logs​

journalctl -u zetavisor -f

Monitoring​

In a production environment we recommend monitoring the node resources (CPU load, Memory Usage, Disk usage and Disk IO) for any performance degradation.

ZetaChain Core generates a log that can be monitored for errors and used for troubleshooting. If you install Zetacore as a Systemd service using the instructions above you can view this log with journalctl -o cat -f -u zetacored.

Prometheus can be enabled to serve metrics which can be consumed by Prometheus collector(s). Telemetry include Prometheus metrics can be enabled in the app.toml file. See the CosmosSDK Telemetry Documentation for more information.

ZetaVisor Environment Variables​

Breif explanation of the environment variables used by zetavisor.

  • DAEMON_HOME

    • The location where the zetavisor/ directory is kept that contains the genesis binary, the upgrade binaries, and any additional auxiliary files associated with each binary (e.g. $HOME/.zetacored, etc.).

  • DAEMON_NAME

    • The name of the binary itself (e.g. gaiad, regend, simd, etc.).

  • DAEMON_ALLOW_DOWNLOAD_BINARIES (optional)

    • If set to true, enables auto-downloading of new binaries (for security reasons, this is intended for full nodes rather than validators). By default, zetavisor will not auto-download new binaries.

  • 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), zetavisor stops running after an upgrade and requires the system administrator to manually restart it. Note that restart is only after the upgrade and does not auto-restart the subprocess after an error occurs.

  • DAEMON_DATA_BACKUP_DIR

    • Option to set a custom backup directory. If not set, DAEMON_HOME is used.

  • UNSAFE_SKIP_BACKUP (defaults to false)

    • If set to true, upgrades directly without performing a backup. Otherwise (false, default), backs up the data before trying the upgrade. The default value of false is useful and recommended in case of failures and when a backup is needed to rollback. We recommend using the default backup option UNSAFE_SKIP_BACKUP=false.

  • CLIENT_DAEMON_NAME

    • Top level config for name of core binary

  • AllowDownloadBinaries

    • True : Top level config to allow download during an upgrade
    • False : Top Level config to stop the above

  • CLIENT_SKIP_UPGRADE

    • True :
      • Skips upgrade for the client (Does not replace binary)
        • Note Upgrade includes download also
      • Does not kill the client process at upgrade height
      • Does not start the client after upgrade
      • Use this to completely ignore zetaclient .
    • False: Replaces the client binary at the correct height

  • CLIENT_START_PROCESS

    • True : Starts zetaclientd
    • False : Does not start zetaclientd
    • Note
      • Both RestartAfterUpgrade and StartClientProcess need to be true for this to work
      • SkipClientUpgrade needs to be false and StartClientProcess needs to be true for this to work
    • Use this to tune upgrade process
      • Example : SkipClientUpgrade : false && StartClientProcess false
        • Will do the upgrade , replace binaries etc but starting the client needs to be handled separately
        • Note the client will still be killed at the upgrade height , and new binaries will be copied to the correct location (Dowloaded if allowed)