|
| 1 | +# Cosmovisor Configuration Guide |
| 2 | + |
| 3 | +> 💬 Cosmovisor is a process manager for Cosmos SDK application binaries that automates application binary switch at chain upgrades. It polls the `upgrade-info.json` file that is created by the **x/upgrade** module at upgrade height, and then 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. |
| 4 | +
|
| 5 | +This guide explains the key configuration options for Cosmovisor when running a cheqd node. You can configure these settings via: |
| 6 | + |
| 7 | +* Environment variables |
| 8 | + |
| 9 | +* A `config.toml file` under `$DAEMON_HOME/cosmovisor/` (by default) or any other location passed to cosmovisor with `--cosmovisor-config` flag |
| 10 | + |
| 11 | +> **Note:** Environment variables always take precedence over values set in the config file, if the `--cosmovisor-config` flag is not passed. |
| 12 | +
|
| 13 | +The cheqd node's [interactive installer](https://raw.githubusercontent.com/cheqd/cheqd-node/refs/heads/main/installer/installer.py) sets most of these parameters for you in both the daemon service configuration file (`cheqd-cosmovisor.service`) and as a system-wide environment variable. It will also create a config.toml file, for consistency purposes. Understanding these settings helps with troubleshooting and advanced setups. |
| 14 | + |
| 15 | +## Configuration Parameters |
| 16 | + |
| 17 | +| Parameter | Default Value | Required | Description | Set by Installer | |
| 18 | +|:---------:|:-------------:|:--------:|:------------|:----------------:| |
| 19 | +| `DAEMON_HOME`| `/home/cheqd/.cheqdnode` | Yes | Location of the `cosmovisor/` directory. | ✅ | |
| 20 | +| `DAEMON_NAME` | `cheqd-noded` | Yes | Name of the node binary. Usually doesn’t need to change. | ✅ | |
| 21 | +| `DAEMON_ALLOW_DOWNLOAD_BINARIES` | `true` | No | Allows Cosmovisor to auto-download upgrade binaries. Recommended to be true. | ✅ | |
| 22 | +| `DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM` | `true` | No | Ensures downloaded binaries have checksums. Always true in cheqd upgrade plans. | ✅ | |
| 23 | +| `DAEMON_RESTART_AFTER_UPGRADE` | `true` | No | Automatically restarts node after an upgrade. | ✅ | |
| 24 | +| `DAEMON_RESTART_DELAY` | `30s` | No | Delay before restart after upgrade. 0s is fine for most setups. | ✅ | |
| 25 | +| `DAEMON_SHUTDOWN_GRACE` | `30s` | No | Grace period for clean shutdown. Helps with safe unattended upgrades. | ✅ | |
| 26 | +| `DAEMON_POLL_INTERVAL` | `300s` | No | How often to check for upgrade plans. | ❌ | |
| 27 | +| `DAEMON_DATA_BACKUP_DIR` | `DAEMON_HOME`| No | Custom directory for pre-upgrade backups. Requires extra storage. | ❌ | |
| 28 | +| `UNSAFE_SKIP_BACKUP` | `true` | No | Set to false to enable auto-backups (slower and storage-heavy). | ✅ | |
| 29 | +| `DAEMON_PREUPGRADE_MAX_RETRIES` | `0` | No | Max retries for pre-upgrade hook (exit code 31). | ❌ | |
| 30 | +| `COSMOVISOR_DISABLE_LOGS` | `false`| No | Disable Cosmovisor logs (not the node logs). | ❌ | |
| 31 | +| `COSMOVISOR_COLOR_LOGS` | `true` | No | Enables colored logs for easier readability. | ❌. | |
| 32 | +| `COSMOVISOR_TIMEFORMAT_LOGS` | `kitchen` | No | Time format for logs (e.g., 3:04PM). Other formats: rfc3339, unix, etc. | ❌ | |
| 33 | +| `COSMOVISOR_CUSTOM_PREUPGRADE` | '' | No | Path to a custom pre-upgrade script. It should be located under `$DAEMON_HOME/cosmovisor/`. | ❌ | |
| 34 | +| `COSMOVISOR_DISABLE_RECASE` | `false` | No | Enforces exact case matching for upgrade plan directories. | ❌ | |
| 35 | + |
| 36 | +--- |
| 37 | + |
| 38 | +## 📝 Additional Notes |
| 39 | + |
| 40 | +* **Backups**: Enabling backups can use significant disk space and time. Use with caution, especially on non-pruned nodes. |
| 41 | +* **Custom Pre-upgrade Scripts**: Use COSMOVISOR_CUSTOM_PREUPGRADE for advanced automation (e.g., state export). |
| 42 | +* **Log Time Format**: kitchen is human-readable. See [Go time formats](https://pkg.go.dev/time#pkg-constants) for more options. |
| 43 | + |
| 44 | +## 🔧 Example: systemd Service File |
| 45 | + |
| 46 | +To set Cosmovisor parameters at the service level, you can edit the systemd service file, typically located at `/usr/lib/systemd/system/cheqd-cosmovisor.service`. Here is an example with custom values: |
| 47 | + |
| 48 | +```ini |
| 49 | +[Unit] |
| 50 | +Description=Service for running cheqd-noded daemon |
| 51 | +After=network.target |
| 52 | +Documentation=https://docs.cheqd.io/node |
| 53 | + |
| 54 | +[Service] |
| 55 | +Environment="DAEMON_HOME=/home/cheqd/.cheqdnode" |
| 56 | +Environment="DAEMON_NAME=cheqd-noded" |
| 57 | +Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true" |
| 58 | +Environment="DAEMON_RESTART_AFTER_UPGRADE=true" |
| 59 | +Environment="DAEMON_POLL_INTERVAL=300s" |
| 60 | +Environment="UNSAFE_SKIP_BACKUP=false" |
| 61 | +Environment="DAEMON_RESTART_DELAY=30s" |
| 62 | +Environment="DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM=true" |
| 63 | +Environment="DAEMON_SHUTDOWN_GRACE=30s" |
| 64 | + |
| 65 | +Type=simple |
| 66 | +User=cheqd |
| 67 | +ExecStart=/usr/bin/cosmovisor run start |
| 68 | +Restart=on-failure |
| 69 | +RestartSec=30 |
| 70 | +StartLimitBurst=5 |
| 71 | +StartLimitInterval=60 |
| 72 | +TimeoutSec=120 |
| 73 | +StandardOutput=journal |
| 74 | +StandardError=journal |
| 75 | +SyslogIdentifier=cosmovisor |
| 76 | +LimitNOFILE=65535 |
| 77 | + |
| 78 | +[Install] |
| 79 | +WantedBy=multi-user.target |
| 80 | +``` |
| 81 | + |
| 82 | +If you decide to use config.toml file instead, feel free to remove environment variables from daemon service file and add `--cosmovisor-config` to your config file, i.e. `ExecStart=/usr/bin/cosmovisor run start --cosmovisor-config /home/cheqd/.cheqdnode/cosmovisor/config.toml`. |
| 83 | + |
| 84 | +> **⚠️ Important**: If you manually modify this file, the cheqd installer may overwrite your changes. When prompted during future installs, **decline the update** to preserve your custom settings. |
| 85 | +
|
| 86 | +## 🛠 Example: config.toml File |
| 87 | + |
| 88 | +```toml |
| 89 | +daemon_home = '/home/cheqd/.cheqdnode' |
| 90 | +daemon_name = 'cheqd-noded' |
| 91 | +daemon_allow_download_binaries = true |
| 92 | +daemon_download_must_have_checksum = true |
| 93 | +daemon_restart_after_upgrade = true |
| 94 | +daemon_restart_delay = '30s' |
| 95 | +daemon_shutdown_grace = '30s' |
| 96 | +daemon_poll_interval = '300s' |
| 97 | +unsafe_skip_backup = true |
| 98 | +daemon_data_backup_dir = '/home/cheqd/.cheqdnode' |
| 99 | +daemon_preupgrade_max_retries = 0 |
| 100 | +daemon_grpc_address = 'localhost:9090' |
| 101 | +cosmovisor_disable_logs = false |
| 102 | +cosmovisor_color_logs = true |
| 103 | +cosmovisor_timeformat_logs = 'kitchen' |
| 104 | +cosmovisor_custom_preupgrade = '' |
| 105 | +cosmovisor_disable_recase = false |
| 106 | +``` |
| 107 | + |
| 108 | +> **⚠️ Reminder**: Like the service file, custom config.toml changes can be overwritten by the installer. **Decline updates** if you’ve made manual modifications. |
| 109 | +
|
| 110 | +For further details, refer to the official [Cosmovisor documentation](https://docs.cosmos.network/main/tooling/cosmovisor). |
0 commit comments