From b7b2b059cdc91c58dfd12001ec8d7ff801966f87 Mon Sep 17 00:00:00 2001 From: filipdjokic Date: Tue, 6 May 2025 14:11:41 +0200 Subject: [PATCH 1/7] docs: Add guide for cosmovisor configuration --- SUMMARY.md | 1 + docs/setup-and-configure/README.md | 2 + .../cosmovisor-configuration.md | 77 +++++++++++++++++++ 3 files changed, 80 insertions(+) create mode 100644 docs/setup-and-configure/cosmovisor-configuration.md diff --git a/SUMMARY.md b/SUMMARY.md index 715e771..1c34e6c 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -7,6 +7,7 @@ * [Setup a new cheqd node](docs/setup-and-configure/README.md) * [Pre-Requisites & Requirements](docs/setup-and-configure/requirements.md) * [(Alternative) Install with Docker](docs/setup-and-configure/docker.md) + * [Configure cosmovisor](docs/setup-and-configure/cosmovisor-configuration.md) * [Command Line usage](docs/cheqd-cli/README.md) * [Manage keys](docs/cheqd-cli/cheqd-cli-key-management.md) * [Manage accounts](docs/cheqd-cli/cheqd-cli-accounts.md) diff --git a/docs/setup-and-configure/README.md b/docs/setup-and-configure/README.md index 6463eb6..87a442b 100644 --- a/docs/setup-and-configure/README.md +++ b/docs/setup-and-configure/README.md @@ -309,3 +309,5 @@ If the node is catching up, the time needed to fully catch up will depend on how ## Next steps If you're configuring a validator, check out [**our validator guide**](../validator-guide/README.md) for further configuration steps to carry out. + +Additonally, you read [**here**](./cosmovisor-configuration.md) about cosmovisor-specific configuration parameters and how to change them. diff --git a/docs/setup-and-configure/cosmovisor-configuration.md b/docs/setup-and-configure/cosmovisor-configuration.md new file mode 100644 index 0000000..247ea3e --- /dev/null +++ b/docs/setup-and-configure/cosmovisor-configuration.md @@ -0,0 +1,77 @@ +# Cosmovisor Configuration Guide + +This guide explains the key Cosmovisor configuration parameters recommended for cheqd node operators. These settings can be applied as environment variables, in a `config.toml` file under `$DAEMON_HOME/cosmovisor/`, or via a custom path using the `--cosmovisor-config-file` flag at startup. + +> **Note:** Environment variables always take precedence over values set in the config file. The interactive installer for cheqd nodes sets most of these parameters for you in both the daemon service configuration file (`cheqd-cosmovisor.service`) and as a system-wide environment variable. Understanding these settings helps with troubleshooting and advanced setups. + +--- + +## Configuration Parameters + +| Parameter | Default Value | Required | Description | Set by Installer | Comments/Recommendations | +|:---------:|:-------------:|:--------:|:------------|:----------------:|:-------------------------| +| `DAEMON_HOME`| `/home/cheqd/.cheqdnode` | Yes | Location of the `cosmovisor/` directory. | Yes | Unless you installed your cheqd node at different location, you should stick to default value. | +| `DAEMON_NAME` | `cheqd-noded` | Yes | Name of the node binary. | Yes | For most users, the default value should be fine. | +| `DAEMON_ALLOW_DOWNLOAD_BINARIES` | `true` | No | Enable/disable auto-download of upgrade binaries. | Yes | Set to `true` for smoother, unattended upgrades. | +| `DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM` | `true` | No | Require binary checksums in upgrade plans. | Yes | By default, we include checksums in our upgrade plans. | +| `DAEMON_RESTART_AFTER_UPGRADE` | `true` | No | Automatically restart after upgrade. | Yes | Leave the default value in case you want fully-automated upgrades. | +| `DAEMON_RESTART_DELAY` | `0` | No | Delay (in seconds) between upgrade and restart. | No | `0` is fine for most setups. | +| `DAEMON_SHUTDOWN_GRACE` | `30s` | No | Grace period (in seconds) for shutdown to allow cleanup before force kill. | Yes | For safer undattended upgrades. | +| `DAEMON_POLL_INTERVAL` | `300ms` | No | How often to poll for upgrade plans (locally - looking for upgrade-info.json file). | No | Default is frequent; `60s` is often sufficient. | +| `DAEMON_DATA_BACKUP_DIR` | `DAEMON_HOME`| No | Custom backup directory. | No | Set if you want to enable backups at specific locations. Note that this will require a lot of additional storage, since it will backup whole data directory before upgrade is attempted. | +| `UNSAFE_SKIP_BACKUP` | `true` | No | Skip backup before upgrade. | Yes | Set to false to enable automatic backups before each upgrade. Note that this will take a lot of time and storage, especially on bigger, non-pruned nodes. | +| `DAEMON_PREUPGRADE_MAX_RETRIES` | `0` | No | Max retries for pre-upgrade handler after exit status 31. | No | If not changed, the daemon will retry upgrades until succeeds or gets stopped. | +| `COSMOVISOR_DISABLE_LOGS` | `false`| No | Disable Cosmovisor logs (not the node logs). | No | For most users, the default value should be fine. | +| `COSMOVISOR_COLOR_LOGS` | `true` | No | Enable colored Cosmovisor logs. | No. | For most users, the default value should be fine. | +| `COSMOVISOR_TIMEFORMAT_LOGS` | `kitchen` | No | Timestamp format for logs. | No | `kitchen` = `3:04PM`; other options: `ansic`, `unix`, `ruby`, `rfc822`, `rfc3339`, `rfc3339nano`. For most users, the default value should be fine. | +| `COSMOVISOR_CUSTOM_PREUPGRADE` | '' | No | Path to script you want to run before upgrade (`$DAEMON_HOME/cosmovisor/$COSMOVISOR_CUSTOM_PREUPGRADE`). | No | Use this for setting up some custom pre-upgrade actions (like backups or state exports) | +| `COSMOVISOR_DISABLE_RECASE` | `false` | No | If `true`, upgrade directory must match plan name exactly (case-sensitive). | No | For most users, the default value should be fine. | + +--- + +## Additional Notes + +- **Backups:** Cosmovisor can back up your node data before upgrades. The backup size depends on your node's data directory. Ensure you have enough disk space. +- **Pre-upgrade Handler:** The `DAEMON_PREUPGRADE_MAX_RETRIES` parameter is for advanced use cases where the Cosmos SDK app implements a pre-upgrade handler. +- **Log Time Formats:** The `COSMOVISOR_TIMEFORMAT_LOGS` parameter supports several formats. `kitchen` is a human-readable time (e.g., `3:04PM`). For more, see [Go time formats](https://pkg.go.dev/time#pkg-constants). + +## Example: Modifying the Cosmovisor Systemd Service File + +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: + +```ini +[Unit] +Description=Service for running cheqd-noded daemon +After=network.target +Documentation=https://docs.cheqd.io/node + +[Service] +Environment="DAEMON_HOME=/home/cheqd/.cheqdnode" +Environment="DAEMON_NAME=cheqd-noded" +Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true" +Environment="DAEMON_RESTART_AFTER_UPGRADE=true" +Environment="DAEMON_POLL_INTERVAL=300s" +Environment="UNSAFE_SKIP_BACKUP=true" +Environment="DAEMON_RESTART_DELAY=120s" +Type=simple +User=cheqd +ExecStart=/usr/bin/cosmovisor run start +Restart=on-failure +RestartSec=30 +StartLimitBurst=5 +StartLimitInterval=60 +TimeoutSec=120 +StandardOutput=journal +StandardError=journal +SyslogIdentifier=cosmovisor +LimitNOFILE=65535 + +[Install] +WantedBy=multi-user.target +``` + +> **Important:** If you manually modify the service file, ensure these changes are not overwritten by the interactive installer at future executions. When prompted by the installer to update the cosmovisor daemon file, **decline** to preserve your custom settings. + +--- + +For more details, see the [Cosmovisor documentation](https://docs.cosmos.network/main/tooling/cosmovisor). From eb57d8bc381a15b17938ec979c39f68e1ed8ba53 Mon Sep 17 00:00:00 2001 From: filipdjokic Date: Tue, 6 May 2025 14:55:54 +0200 Subject: [PATCH 2/7] Update docs --- .../cosmovisor-configuration.md | 35 ++++++++++++++++--- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/docs/setup-and-configure/cosmovisor-configuration.md b/docs/setup-and-configure/cosmovisor-configuration.md index 247ea3e..3c2e46c 100644 --- a/docs/setup-and-configure/cosmovisor-configuration.md +++ b/docs/setup-and-configure/cosmovisor-configuration.md @@ -15,7 +15,7 @@ This guide explains the key Cosmovisor configuration parameters recommended for | `DAEMON_ALLOW_DOWNLOAD_BINARIES` | `true` | No | Enable/disable auto-download of upgrade binaries. | Yes | Set to `true` for smoother, unattended upgrades. | | `DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM` | `true` | No | Require binary checksums in upgrade plans. | Yes | By default, we include checksums in our upgrade plans. | | `DAEMON_RESTART_AFTER_UPGRADE` | `true` | No | Automatically restart after upgrade. | Yes | Leave the default value in case you want fully-automated upgrades. | -| `DAEMON_RESTART_DELAY` | `0` | No | Delay (in seconds) between upgrade and restart. | No | `0` is fine for most setups. | +| `DAEMON_RESTART_DELAY` | `30s` | No | Delay (in seconds) between upgrade and restart. | Yes | `0` is fine for most setups. | | `DAEMON_SHUTDOWN_GRACE` | `30s` | No | Grace period (in seconds) for shutdown to allow cleanup before force kill. | Yes | For safer undattended upgrades. | | `DAEMON_POLL_INTERVAL` | `300ms` | No | How often to poll for upgrade plans (locally - looking for upgrade-info.json file). | No | Default is frequent; `60s` is often sufficient. | | `DAEMON_DATA_BACKUP_DIR` | `DAEMON_HOME`| No | Custom backup directory. | No | Set if you want to enable backups at specific locations. Note that this will require a lot of additional storage, since it will backup whole data directory before upgrade is attempted. | @@ -50,9 +50,12 @@ Environment="DAEMON_HOME=/home/cheqd/.cheqdnode" Environment="DAEMON_NAME=cheqd-noded" Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true" Environment="DAEMON_RESTART_AFTER_UPGRADE=true" -Environment="DAEMON_POLL_INTERVAL=300s" -Environment="UNSAFE_SKIP_BACKUP=true" -Environment="DAEMON_RESTART_DELAY=120s" +Environment="DAEMON_POLL_INTERVAL=30s" +Environment="UNSAFE_SKIP_BACKUP=false" +Environment="DAEMON_RESTART_DELAY=30s" +ENVIRONMENT="DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM=true" +ENVIRONMENT="DAEMON_SHUTDOWN_GRACE=30s" + Type=simple User=cheqd ExecStart=/usr/bin/cosmovisor run start @@ -74,4 +77,28 @@ WantedBy=multi-user.target --- +## Example: Cosmovisor config.toml file + +```toml +daemon_home = '/home/cheqd/.cheqdnode' +daemon_name = 'cheqd-noded' +daemon_allow_download_binaries = true +daemon_download_must_have_checksum = true +daemon_restart_after_upgrade = true +daemon_restart_delay = 30s +daemon_shutdown_grace = 30s +daemon_poll_interval = 300000000000 +unsafe_skip_backup = true +daemon_data_backup_dir = '/home/cheqd/.cheqdnode' +daemon_preupgrade_max_retries = 0 +daemon_grpc_address = 'localhost:9090' +cosmovisor_disable_logs = false +cosmovisor_color_logs = true +cosmovisor_timeformat_logs = 'kitchen' +cosmovisor_custom_preupgrade = '' +cosmovisor_disable_recase = false +``` + +> **Important:** If you manually modify the config.toml file, ensure these changes are not overwritten by the interactive installer at future executions. When prompted by the installer to update the cosmovisor config.toml file, **decline** to preserve your custom settings. + For more details, see the [Cosmovisor documentation](https://docs.cosmos.network/main/tooling/cosmovisor). From 4a7743455edda7451cc5114adc4b8e2f85f2be28 Mon Sep 17 00:00:00 2001 From: filipdjokic Date: Tue, 6 May 2025 15:01:06 +0200 Subject: [PATCH 3/7] Update docs --- docs/setup-and-configure/cosmovisor-configuration.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/setup-and-configure/cosmovisor-configuration.md b/docs/setup-and-configure/cosmovisor-configuration.md index 3c2e46c..44402a0 100644 --- a/docs/setup-and-configure/cosmovisor-configuration.md +++ b/docs/setup-and-configure/cosmovisor-configuration.md @@ -1,6 +1,6 @@ # Cosmovisor Configuration Guide -This guide explains the key Cosmovisor configuration parameters recommended for cheqd node operators. These settings can be applied as environment variables, in a `config.toml` file under `$DAEMON_HOME/cosmovisor/`, or via a custom path using the `--cosmovisor-config-file` flag at startup. +This guide explains the key Cosmovisor configuration parameters recommended for cheqd node operators. These settings can be applied as environment variables, in a `config.toml` file under `$DAEMON_HOME/cosmovisor/`, or via a custom path using the `--cosmovisor-config` flag at startup. > **Note:** Environment variables always take precedence over values set in the config file. The interactive installer for cheqd nodes sets most of these parameters for you in both the daemon service configuration file (`cheqd-cosmovisor.service`) and as a system-wide environment variable. Understanding these settings helps with troubleshooting and advanced setups. @@ -53,8 +53,8 @@ Environment="DAEMON_RESTART_AFTER_UPGRADE=true" Environment="DAEMON_POLL_INTERVAL=30s" Environment="UNSAFE_SKIP_BACKUP=false" Environment="DAEMON_RESTART_DELAY=30s" -ENVIRONMENT="DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM=true" -ENVIRONMENT="DAEMON_SHUTDOWN_GRACE=30s" +Environment="DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM=true" +Environment="DAEMON_SHUTDOWN_GRACE=30s" Type=simple User=cheqd @@ -73,6 +73,8 @@ LimitNOFILE=65535 WantedBy=multi-user.target ``` +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`. + > **Important:** If you manually modify the service file, ensure these changes are not overwritten by the interactive installer at future executions. When prompted by the installer to update the cosmovisor daemon file, **decline** to preserve your custom settings. --- From 4e2fdc7d7de1a364e6c1731eac15a702102ef14d Mon Sep 17 00:00:00 2001 From: filipdjokic Date: Tue, 6 May 2025 15:03:38 +0200 Subject: [PATCH 4/7] Remove dividers --- docs/setup-and-configure/cosmovisor-configuration.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/setup-and-configure/cosmovisor-configuration.md b/docs/setup-and-configure/cosmovisor-configuration.md index 44402a0..6152497 100644 --- a/docs/setup-and-configure/cosmovisor-configuration.md +++ b/docs/setup-and-configure/cosmovisor-configuration.md @@ -4,8 +4,6 @@ This guide explains the key Cosmovisor configuration parameters recommended for > **Note:** Environment variables always take precedence over values set in the config file. The interactive installer for cheqd nodes sets most of these parameters for you in both the daemon service configuration file (`cheqd-cosmovisor.service`) and as a system-wide environment variable. Understanding these settings helps with troubleshooting and advanced setups. ---- - ## Configuration Parameters | Parameter | Default Value | Required | Description | Set by Installer | Comments/Recommendations | @@ -77,8 +75,6 @@ If you decide to use config.toml file instead, feel free to remove environment v > **Important:** If you manually modify the service file, ensure these changes are not overwritten by the interactive installer at future executions. When prompted by the installer to update the cosmovisor daemon file, **decline** to preserve your custom settings. ---- - ## Example: Cosmovisor config.toml file ```toml From ef323bc78e933759eead7c2cd2a48c4bc7f2feb0 Mon Sep 17 00:00:00 2001 From: filipdjokic Date: Tue, 6 May 2025 15:20:09 +0200 Subject: [PATCH 5/7] Update cosmovisor variables --- docs/setup-and-configure/cosmovisor-configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/setup-and-configure/cosmovisor-configuration.md b/docs/setup-and-configure/cosmovisor-configuration.md index 6152497..84a620c 100644 --- a/docs/setup-and-configure/cosmovisor-configuration.md +++ b/docs/setup-and-configure/cosmovisor-configuration.md @@ -83,9 +83,9 @@ daemon_name = 'cheqd-noded' daemon_allow_download_binaries = true daemon_download_must_have_checksum = true daemon_restart_after_upgrade = true -daemon_restart_delay = 30s -daemon_shutdown_grace = 30s -daemon_poll_interval = 300000000000 +daemon_restart_delay = '30s' +daemon_shutdown_grace = '30s' +daemon_poll_interval = '300s' unsafe_skip_backup = true daemon_data_backup_dir = '/home/cheqd/.cheqdnode' daemon_preupgrade_max_retries = 0 From 182ab9ad49328b786a1939b90650eba786282e56 Mon Sep 17 00:00:00 2001 From: filipdjokic Date: Tue, 6 May 2025 17:45:53 +0200 Subject: [PATCH 6/7] Update phrasing --- .../cosmovisor-configuration.md | 64 ++++++++++--------- 1 file changed, 35 insertions(+), 29 deletions(-) diff --git a/docs/setup-and-configure/cosmovisor-configuration.md b/docs/setup-and-configure/cosmovisor-configuration.md index 84a620c..c2bcc97 100644 --- a/docs/setup-and-configure/cosmovisor-configuration.md +++ b/docs/setup-and-configure/cosmovisor-configuration.md @@ -1,39 +1,45 @@ # Cosmovisor Configuration Guide -This guide explains the key Cosmovisor configuration parameters recommended for cheqd node operators. These settings can be applied as environment variables, in a `config.toml` file under `$DAEMON_HOME/cosmovisor/`, or via a custom path using the `--cosmovisor-config` flag at startup. +This guide explains the key configuration options for Cosmovisor when running a cheqd node. You can configure these settings via: -> **Note:** Environment variables always take precedence over values set in the config file. The interactive installer for cheqd nodes sets most of these parameters for you in both the daemon service configuration file (`cheqd-cosmovisor.service`) and as a system-wide environment variable. Understanding these settings helps with troubleshooting and advanced setups. +* Environment variables + +* A `config.toml file` under `$DAEMON_HOME/cosmovisor/` (by default) or any other location passed to cosmovisor with `--cosmovisor-config` flag + +> **Note:** Environment variables always take precedence over values set in the config file, if the `--cosmovisor-config` flag is not passed. + +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. ## Configuration Parameters -| Parameter | Default Value | Required | Description | Set by Installer | Comments/Recommendations | -|:---------:|:-------------:|:--------:|:------------|:----------------:|:-------------------------| -| `DAEMON_HOME`| `/home/cheqd/.cheqdnode` | Yes | Location of the `cosmovisor/` directory. | Yes | Unless you installed your cheqd node at different location, you should stick to default value. | -| `DAEMON_NAME` | `cheqd-noded` | Yes | Name of the node binary. | Yes | For most users, the default value should be fine. | -| `DAEMON_ALLOW_DOWNLOAD_BINARIES` | `true` | No | Enable/disable auto-download of upgrade binaries. | Yes | Set to `true` for smoother, unattended upgrades. | -| `DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM` | `true` | No | Require binary checksums in upgrade plans. | Yes | By default, we include checksums in our upgrade plans. | -| `DAEMON_RESTART_AFTER_UPGRADE` | `true` | No | Automatically restart after upgrade. | Yes | Leave the default value in case you want fully-automated upgrades. | -| `DAEMON_RESTART_DELAY` | `30s` | No | Delay (in seconds) between upgrade and restart. | Yes | `0` is fine for most setups. | -| `DAEMON_SHUTDOWN_GRACE` | `30s` | No | Grace period (in seconds) for shutdown to allow cleanup before force kill. | Yes | For safer undattended upgrades. | -| `DAEMON_POLL_INTERVAL` | `300ms` | No | How often to poll for upgrade plans (locally - looking for upgrade-info.json file). | No | Default is frequent; `60s` is often sufficient. | -| `DAEMON_DATA_BACKUP_DIR` | `DAEMON_HOME`| No | Custom backup directory. | No | Set if you want to enable backups at specific locations. Note that this will require a lot of additional storage, since it will backup whole data directory before upgrade is attempted. | -| `UNSAFE_SKIP_BACKUP` | `true` | No | Skip backup before upgrade. | Yes | Set to false to enable automatic backups before each upgrade. Note that this will take a lot of time and storage, especially on bigger, non-pruned nodes. | -| `DAEMON_PREUPGRADE_MAX_RETRIES` | `0` | No | Max retries for pre-upgrade handler after exit status 31. | No | If not changed, the daemon will retry upgrades until succeeds or gets stopped. | -| `COSMOVISOR_DISABLE_LOGS` | `false`| No | Disable Cosmovisor logs (not the node logs). | No | For most users, the default value should be fine. | -| `COSMOVISOR_COLOR_LOGS` | `true` | No | Enable colored Cosmovisor logs. | No. | For most users, the default value should be fine. | -| `COSMOVISOR_TIMEFORMAT_LOGS` | `kitchen` | No | Timestamp format for logs. | No | `kitchen` = `3:04PM`; other options: `ansic`, `unix`, `ruby`, `rfc822`, `rfc3339`, `rfc3339nano`. For most users, the default value should be fine. | -| `COSMOVISOR_CUSTOM_PREUPGRADE` | '' | No | Path to script you want to run before upgrade (`$DAEMON_HOME/cosmovisor/$COSMOVISOR_CUSTOM_PREUPGRADE`). | No | Use this for setting up some custom pre-upgrade actions (like backups or state exports) | -| `COSMOVISOR_DISABLE_RECASE` | `false` | No | If `true`, upgrade directory must match plan name exactly (case-sensitive). | No | For most users, the default value should be fine. | +| Parameter | Default Value | Required | Description | Set by Installer | +|:---------:|:-------------:|:--------:|:------------|:----------------:| +| `DAEMON_HOME`| `/home/cheqd/.cheqdnode` | Yes | Location of the `cosmovisor/` directory. | ✅ | +| `DAEMON_NAME` | `cheqd-noded` | Yes | Name of the node binary. Usually doesn’t need to change. | ✅ | +| `DAEMON_ALLOW_DOWNLOAD_BINARIES` | `true` | No | Allows Cosmovisor to auto-download upgrade binaries. Recommended to be true. | ✅ | +| `DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM` | `true` | No | Ensures downloaded binaries have checksums. Always true in cheqd upgrade plans. | ✅ | +| `DAEMON_RESTART_AFTER_UPGRADE` | `true` | No | Automatically restarts node after an upgrade. | ✅ | +| `DAEMON_RESTART_DELAY` | `30s` | No | Delay before restart after upgrade. 0s is fine for most setups. | ✅ | +| `DAEMON_SHUTDOWN_GRACE` | `30s` | No | Grace period for clean shutdown. Helps with safe unattended upgrades. | ✅ | +| `DAEMON_POLL_INTERVAL` | `300s` | No | How often to check for upgrade plans. | ❌ | +| `DAEMON_DATA_BACKUP_DIR` | `DAEMON_HOME`| No | Custom directory for pre-upgrade backups. Requires extra storage. | ❌ | +| `UNSAFE_SKIP_BACKUP` | `true` | No | Set to false to enable auto-backups (slower and storage-heavy). | ✅ | +| `DAEMON_PREUPGRADE_MAX_RETRIES` | `0` | No | Max retries for pre-upgrade hook (exit code 31). | ❌ | +| `COSMOVISOR_DISABLE_LOGS` | `false`| No | Disable Cosmovisor logs (not the node logs). | ❌ | +| `COSMOVISOR_COLOR_LOGS` | `true` | No | Enables colored logs for easier readability. | ❌. | +| `COSMOVISOR_TIMEFORMAT_LOGS` | `kitchen` | No | Time format for logs (e.g., 3:04PM). Other formats: rfc3339, unix, etc. | ❌ | +| `COSMOVISOR_CUSTOM_PREUPGRADE` | '' | No | Path to a custom pre-upgrade script. It should be located under `$DAEMON_HOME/cosmovisor/`. | ❌ | +| `COSMOVISOR_DISABLE_RECASE` | `false` | No | Enforces exact case matching for upgrade plan directories. | ❌ | --- -## Additional Notes +## 📝 Additional Notes -- **Backups:** Cosmovisor can back up your node data before upgrades. The backup size depends on your node's data directory. Ensure you have enough disk space. -- **Pre-upgrade Handler:** The `DAEMON_PREUPGRADE_MAX_RETRIES` parameter is for advanced use cases where the Cosmos SDK app implements a pre-upgrade handler. -- **Log Time Formats:** The `COSMOVISOR_TIMEFORMAT_LOGS` parameter supports several formats. `kitchen` is a human-readable time (e.g., `3:04PM`). For more, see [Go time formats](https://pkg.go.dev/time#pkg-constants). +* **Backups**: Enabling backups can use significant disk space and time. Use with caution, especially on non-pruned nodes. +* **Custom Pre-upgrade Scripts**: Use COSMOVISOR_CUSTOM_PREUPGRADE for advanced automation (e.g., state export). +* **Log Time Format**: kitchen is human-readable. See [Go time formats](https://pkg.go.dev/time#pkg-constants) for more options. -## Example: Modifying the Cosmovisor Systemd Service File +## 🔧 Example: systemd Service File 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: @@ -48,7 +54,7 @@ Environment="DAEMON_HOME=/home/cheqd/.cheqdnode" Environment="DAEMON_NAME=cheqd-noded" Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true" Environment="DAEMON_RESTART_AFTER_UPGRADE=true" -Environment="DAEMON_POLL_INTERVAL=30s" +Environment="DAEMON_POLL_INTERVAL=300s" Environment="UNSAFE_SKIP_BACKUP=false" Environment="DAEMON_RESTART_DELAY=30s" Environment="DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM=true" @@ -73,9 +79,9 @@ WantedBy=multi-user.target 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`. -> **Important:** If you manually modify the service file, ensure these changes are not overwritten by the interactive installer at future executions. When prompted by the installer to update the cosmovisor daemon file, **decline** to preserve your custom settings. +> **⚠️ 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. -## Example: Cosmovisor config.toml file +## 🛠 Example: config.toml File ```toml daemon_home = '/home/cheqd/.cheqdnode' @@ -97,6 +103,6 @@ cosmovisor_custom_preupgrade = '' cosmovisor_disable_recase = false ``` -> **Important:** If you manually modify the config.toml file, ensure these changes are not overwritten by the interactive installer at future executions. When prompted by the installer to update the cosmovisor config.toml file, **decline** to preserve your custom settings. +> **⚠️ Reminder**: Like the service file, custom config.toml changes can be overwritten by the installer. **Decline updates** if you’ve made manual modifications. For more details, see the [Cosmovisor documentation](https://docs.cosmos.network/main/tooling/cosmovisor). From 08b41818d909dbd4bda6624a543913ea3a9043ca Mon Sep 17 00:00:00 2001 From: filipdjokic Date: Tue, 6 May 2025 17:52:08 +0200 Subject: [PATCH 7/7] Add small intro about Cosmovisor --- docs/setup-and-configure/cosmovisor-configuration.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/setup-and-configure/cosmovisor-configuration.md b/docs/setup-and-configure/cosmovisor-configuration.md index c2bcc97..d3bdcd9 100644 --- a/docs/setup-and-configure/cosmovisor-configuration.md +++ b/docs/setup-and-configure/cosmovisor-configuration.md @@ -1,5 +1,7 @@ # Cosmovisor Configuration Guide +> 💬 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. + This guide explains the key configuration options for Cosmovisor when running a cheqd node. You can configure these settings via: * Environment variables @@ -105,4 +107,4 @@ cosmovisor_disable_recase = false > **⚠️ Reminder**: Like the service file, custom config.toml changes can be overwritten by the installer. **Decline updates** if you’ve made manual modifications. -For more details, see the [Cosmovisor documentation](https://docs.cosmos.network/main/tooling/cosmovisor). +For further details, refer to the official [Cosmovisor documentation](https://docs.cosmos.network/main/tooling/cosmovisor).