From 3ab33cabe121c0bb856ef98e1018e90586cbe5eb Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Sun, 5 Nov 2023 22:45:21 +0100 Subject: [PATCH] docs: clarify cosmovisor doc --- tools/cosmovisor/README.md | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/tools/cosmovisor/README.md b/tools/cosmovisor/README.md index 49dda0b354db..4fc827ca7ac7 100644 --- a/tools/cosmovisor/README.md +++ b/tools/cosmovisor/README.md @@ -4,22 +4,24 @@ sidebar_position: 1 # Cosmovisor -`cosmovisor` is a 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. +`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 in `BeginBlocker` when an upgrade is detected and the blockchain reaches the upgrade height. * [Design](#design) * [Contributing](#contributing) * [Setup](#setup) - * [Installation](#installation) - * [Command Line Arguments And Environment Variables](#command-line-arguments-and-environment-variables) - * [Folder Layout](#folder-layout) + * [Installation](#installation) + * [Command Line Arguments And Environment Variables](#command-line-arguments-and-environment-variables) + * [Folder Layout](#folder-layout) * [Usage](#usage) - * [Initialization](#initialization) - * [Detecting Upgrades](#detecting-upgrades) - * [Auto-Download](#auto-download) + * [Initialization](#initialization) + * [Detecting Upgrades](#detecting-upgrades) + * [Adding Upgrade Binary](#adding-upgrade-binary) + * [Auto-Download](#auto-download) * [Example: SimApp Upgrade](#example-simapp-upgrade) - * [Chain Setup](#chain-setup) - * [Prepare Cosmovisor and Start the Chain](#prepare-cosmovisor-and-start-the-chain) - * [Update App](#update-app) + * [Chain Setup](#chain-setup) + * [Prepare Cosmovisor and Start the Chain](#prepare-cosmovisor-and-start-the-chain) + * [Update App](#update-app) ## Design @@ -32,7 +34,9 @@ Cosmovisor is designed to be used as a wrapper for a `Cosmos SDK` app: *Note: If new versions of the application are not set up to run in-place store migrations, migrations will need to be run manually before restarting `cosmovisor` with the new binary. For this reason, we recommend applications adopt in-place store migrations.* -*Note: Only the last version of cosmovisor is actively developed/maintained.* +:::tip +Only the lastest version of cosmovisor is actively developed/maintained. +::: :::warning Versions prior to v1.0.0 have a vulnerability that could lead to a DOS. Please upgrade to the latest version. @@ -126,10 +130,10 @@ Use of `cosmovisor` without one of the action arguments is deprecated. For backw The `cosmovisor/` directory incudes a subdirectory for each version of the application (i.e. `genesis` or `upgrades/`). Within each subdirectory is the application binary (i.e. `bin/$DAEMON_NAME`) and any additional auxiliary files associated with each binary. `current` is a symbolic link to the currently active directory (i.e. `genesis` or `upgrades/`). The `name` variable in `upgrades/` is the lowercased URI-encoded name of the upgrade as specified in the upgrade module plan. Note that the upgrade name path are normalized to be lowercased: for instance, `MyUpgrade` is normalized to `myupgrade`, and its path is `upgrades/myupgrade`. -Please note that `$DAEMON_HOME/cosmovisor` only stores the *application binaries*. The `cosmovisor` binary itself can be stored in any typical location (e.g. `/usr/local/bin`). The application will continue to store its data in the default data directory (e.g. `$HOME/.gaiad`) or the data directory specified with the `--home` flag. `$DAEMON_HOME` is independent of the data directory and can be set to any location. If you set `$DAEMON_HOME` to the same directory as the data directory, you will end up with a configuation like the following: +Please note that `$DAEMON_HOME/cosmovisor` only stores the *application binaries*. The `cosmovisor` binary itself can be stored in any typical location (e.g. `/usr/local/bin`). The application will continue to store its data in the default data directory (e.g. `$HOME/.simapp`) or the data directory specified with the `--home` flag. `$DAEMON_HOME` is independent of the data directory and can be set to any location. If you set `$DAEMON_HOME` to the same directory as the data directory, you will end up with a configuation like the following: ```text -.gaiad +.simapp ├── config ├── data └── cosmovisor @@ -291,8 +295,6 @@ Set up app config: Initialize the node and overwrite any previous genesis file (never do this in a production environment): - - ```shell ./build/simd init test --chain-id test --overwrite ``` @@ -357,7 +359,7 @@ Build the new version `simd` binary: make build ``` -Add the new `simd` binary and the upgrade name: +Add the new `simd` binary and the upgrade name: :::warning