docs: update cosmovisor README (#11136)
## Description General Cosmovisor README update. Closes: #11054 --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [ ] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] added `!` to the type prefix if API or client breaking change - [ ] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [ ] provided a link to the relevant issue or specification - [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules) - [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing) - [ ] added a changelog entry to `CHANGELOG.md` - [ ] included comments for [documenting Go code](https://blog.golang.org/godoc) - [ ] updated the relevant documentation or specification - [ ] reviewed "Files changed" and left comments if necessary - [ ] confirmed all CI checks have passed ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title - [ ] confirmed `!` in the type prefix if API or client breaking change - [ ] confirmed all author checklist items have been addressed - [ ] reviewed state machine logic - [ ] reviewed API design and naming - [ ] reviewed documentation is accurate - [ ] reviewed tests and test coverage - [ ] manually tested (if applicable)
This commit is contained in:
parent
5285d1620b
commit
44d7edd3b0
|
@ -37,7 +37,7 @@ To install a previous version, you can specify the version. IMPORTANT: Chains th
|
||||||
go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v0.1.0
|
go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v0.1.0
|
||||||
```
|
```
|
||||||
|
|
||||||
It is possible to confirm the version of cosmovisor when using Cosmovisor v1.0.0, but it is not possible to do so with `v0.1.0`.
|
You can run `cosmovisor --version` to check the Cosmovisor version (works only with Cosmovisor >=1.0.0).
|
||||||
|
|
||||||
You can also install from source by pulling the cosmos-sdk repository and switching to the correct version and building as follows:
|
You can also install from source by pulling the cosmos-sdk repository and switching to the correct version and building as follows:
|
||||||
|
|
||||||
|
@ -45,14 +45,13 @@ You can also install from source by pulling the cosmos-sdk repository and switch
|
||||||
git clone git@github.com:cosmos/cosmos-sdk
|
git clone git@github.com:cosmos/cosmos-sdk
|
||||||
cd cosmos-sdk
|
cd cosmos-sdk
|
||||||
git checkout cosmovisor/vx.x.x
|
git checkout cosmovisor/vx.x.x
|
||||||
cd cosmovisor
|
make cosmovisor
|
||||||
make
|
|
||||||
```
|
```
|
||||||
|
|
||||||
This will build cosmovisor in your current directory. Afterwards you may want to put it into your machine's PATH like as follows:
|
This will build cosmovisor in `/cosmovisor` directory. Afterwards you may want to put it into your machine's PATH like as follows:
|
||||||
|
|
||||||
```
|
```
|
||||||
cp cosmovisor ~/go/bin/cosmovisor
|
cp cosmovisor/cosmovisor ~/go/bin/cosmovisor
|
||||||
```
|
```
|
||||||
|
|
||||||
*Note: If you are using go `v1.15` or earlier, you will need to use `go get`, and you may want to run the command outside a project directory.*
|
*Note: If you are using go `v1.15` or earlier, you will need to use `go get`, and you may want to run the command outside a project directory.*
|
||||||
|
@ -67,7 +66,7 @@ The first argument passed to `cosmovisor` is the action for `cosmovisor` to take
|
||||||
|
|
||||||
All arguments passed to `cosmovisor run` will be passed to the application binary (as a subprocess). `cosmovisor` will return `/dev/stdout` and `/dev/stderr` of the subprocess as its own. For this reason, `cosmovisor run` cannot accept any command-line arguments other than those available to the application binary.
|
All arguments passed to `cosmovisor run` will be passed to the application binary (as a subprocess). `cosmovisor` will return `/dev/stdout` and `/dev/stderr` of the subprocess as its own. For this reason, `cosmovisor run` cannot accept any command-line arguments other than those available to the application binary.
|
||||||
|
|
||||||
*Note: Use of `cosmovisor` without one of the action arguments is deprecated. For backwards compatability, if the first argument is not an action argument, `run` is assumed. However, this fallback might be removed in future versions, so it is recommended that you always provide `run`.
|
*Note: Use of `cosmovisor` without one of the action arguments is deprecated. For backwards compatibility, if the first argument is not an action argument, `run` is assumed. However, this fallback might be removed in future versions, so it is recommended that you always provide `run`.
|
||||||
|
|
||||||
`cosmovisor` reads its configuration from environment variables:
|
`cosmovisor` reads its configuration from environment variables:
|
||||||
|
|
||||||
|
@ -209,25 +208,22 @@ You can also use `sha512sum` if you would prefer to use longer hashes, or `md5su
|
||||||
|
|
||||||
The following instructions provide a demonstration of `cosmovisor` using the simulation application (`simapp`) shipped with the Cosmos SDK's source code. The following commands are to be run from within the `cosmos-sdk` repository.
|
The following instructions provide a demonstration of `cosmovisor` using the simulation application (`simapp`) shipped with the Cosmos SDK's source code. The following commands are to be run from within the `cosmos-sdk` repository.
|
||||||
|
|
||||||
First, check out the latest `v0.42` release:
|
#### Chain Setup
|
||||||
|
|
||||||
```
|
Let's create a new chain using the `v0.44` version of simapp (the Cosmos SDK demo app):
|
||||||
git checkout v0.42.7
|
|
||||||
```
|
|
||||||
|
|
||||||
Compile the `simd` binary:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
|
git checkout v0.44.6
|
||||||
make build
|
make build
|
||||||
```
|
```
|
||||||
|
|
||||||
Reset `~/.simapp` (never do this in a production environment):
|
Clean `~/.simapp` (never do this in a production environment):
|
||||||
|
|
||||||
```
|
```
|
||||||
./build/simd unsafe-reset-all
|
./build/simd unsafe-reset-all
|
||||||
```
|
```
|
||||||
|
|
||||||
Configure the `simd` binary for testing:
|
Set up app config:
|
||||||
|
|
||||||
```
|
```
|
||||||
./build/simd config chain-id test
|
./build/simd config chain-id test
|
||||||
|
@ -249,7 +245,13 @@ Set the minimum gas price to `0stake` in `~/.simapp/config/app.toml`:
|
||||||
minimum-gas-prices = "0stake"
|
minimum-gas-prices = "0stake"
|
||||||
```
|
```
|
||||||
|
|
||||||
Create a new key for the validator, then add a genesis account and transaction:
|
For the sake of this demonstration, amend `voting_period` in `genesis.json` to a reduced time of 20 seconds (`20s`):
|
||||||
|
|
||||||
|
```
|
||||||
|
cat <<< $(jq '.app_state.gov.voting_params.voting_period = "20s"' $HOME/.simapp/config/genesis.json) > $HOME/.simapp/config/genesis.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Create a validator, and setup genesis transaction:
|
||||||
|
|
||||||
<!-- TODO: add-genesis-account does not read keyring-backend from config -->
|
<!-- TODO: add-genesis-account does not read keyring-backend from config -->
|
||||||
<!-- TODO: gentx does not read chain-id from config -->
|
<!-- TODO: gentx does not read chain-id from config -->
|
||||||
|
@ -261,6 +263,8 @@ Create a new key for the validator, then add a genesis account and transaction:
|
||||||
./build/simd collect-gentxs
|
./build/simd collect-gentxs
|
||||||
```
|
```
|
||||||
|
|
||||||
|
#### Prepare Cosmovisor and Start the Chain
|
||||||
|
|
||||||
Set the required environment variables:
|
Set the required environment variables:
|
||||||
|
|
||||||
```
|
```
|
||||||
|
@ -268,7 +272,7 @@ export DAEMON_NAME=simd
|
||||||
export DAEMON_HOME=$HOME/.simapp
|
export DAEMON_HOME=$HOME/.simapp
|
||||||
```
|
```
|
||||||
|
|
||||||
Set the optional environment variable to trigger an automatic restart:
|
Set the optional environment variable to trigger an automatic app restart:
|
||||||
|
|
||||||
```
|
```
|
||||||
export DAEMON_RESTART_AFTER_UPGRADE=true
|
export DAEMON_RESTART_AFTER_UPGRADE=true
|
||||||
|
@ -281,35 +285,20 @@ mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin
|
||||||
cp ./build/simd $DAEMON_HOME/cosmovisor/genesis/bin
|
cp ./build/simd $DAEMON_HOME/cosmovisor/genesis/bin
|
||||||
```
|
```
|
||||||
|
|
||||||
For the sake of this demonstration, amend `voting_period` in `genesis.json` to a reduced time of 20 seconds (`20s`):
|
Now you can run cosmovisor with simapp v0.44:
|
||||||
|
|
||||||
```
|
```
|
||||||
cat <<< $(jq '.app_state.gov.voting_params.voting_period = "20s"' $HOME/.simapp/config/genesis.json) > $HOME/.simapp/config/genesis.json
|
cosmovisor run start
|
||||||
```
|
```
|
||||||
|
|
||||||
Next, we will hardcode a modification in `simapp` to simulate a code change. In `simapp/app.go`, find the line containing the `UpgradeKeeper` initialization. It should look like the following:
|
|
||||||
|
|
||||||
```go
|
#### Update App
|
||||||
app.UpgradeKeeper = upgradekeeper.NewKeeper(skipUpgradeHeights, keys[upgradetypes.StoreKey], appCodec, homePath)
|
|
||||||
```
|
|
||||||
|
|
||||||
After that line, add the following:
|
Update app to the latest version (e.g. v0.45).
|
||||||
|
|
||||||
```go
|
Next, we can add a migration - which is defined using `x/upgrade` [upgrade plan](https://github.com/cosmos/cosmos-sdk/blob/master/docs/core/upgrade.md) (you may refer to a past version if you are using an older Cosmos SDK release). In a migration we can do any deterministic state change.
|
||||||
app.UpgradeKeeper.SetUpgradeHandler("test1", func(ctx sdk.Context, plan upgradetypes.Plan) {
|
|
||||||
// Add some coins to a random account
|
|
||||||
addr, err := sdk.AccAddressFromBech32("cosmos18cgkqduwuh253twzmhedesw3l7v3fm37sppt58")
|
|
||||||
if err != nil {
|
|
||||||
panic(err)
|
|
||||||
}
|
|
||||||
err = app.BankKeeper.AddCoins(ctx, addr, sdk.Coins{sdk.Coin{Denom: "stake", Amount: sdk.NewInt(345600000)}})
|
|
||||||
if err != nil {
|
|
||||||
panic(err)
|
|
||||||
}
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
Now recompile the `simd` binary with the added upgrade handler:
|
Build the new version `simd` binary:
|
||||||
|
|
||||||
```
|
```
|
||||||
make build
|
make build
|
||||||
|
@ -322,18 +311,13 @@ mkdir -p $DAEMON_HOME/cosmovisor/upgrades/test1/bin
|
||||||
cp ./build/simd $DAEMON_HOME/cosmovisor/upgrades/test1/bin
|
cp ./build/simd $DAEMON_HOME/cosmovisor/upgrades/test1/bin
|
||||||
```
|
```
|
||||||
|
|
||||||
Start `cosmosvisor`:
|
|
||||||
|
|
||||||
```
|
|
||||||
cosmovisor run start
|
|
||||||
```
|
|
||||||
|
|
||||||
Open a new terminal window and submit an upgrade proposal along with a deposit and a vote (these commands must be run within 20 seconds of each other):
|
Open a new terminal window and submit an upgrade proposal along with a deposit and a vote (these commands must be run within 20 seconds of each other):
|
||||||
|
|
||||||
```
|
```
|
||||||
./build/simd tx gov submit-proposal software-upgrade test1 --title upgrade --description upgrade --upgrade-height 20 --from validator --yes
|
./build/simd tx gov submit-proposal software-upgrade test1 --title upgrade --description upgrade --upgrade-height 200 --from validator --yes
|
||||||
./build/simd tx gov deposit 1 10000000stake --from validator --yes
|
./build/simd tx gov deposit 1 10000000stake --from validator --yes
|
||||||
./build/simd tx gov vote 1 yes --from validator --yes
|
./build/simd tx gov vote 1 yes --from validator --yes
|
||||||
```
|
```
|
||||||
|
|
||||||
The upgrade will occur automatically at height 20.
|
The upgrade will occur automatically at height 200. Note: you may need to change the upgrade height in the snippet above if your test play takes more time.
|
||||||
|
|
Loading…
Reference in New Issue