Skip to content

Commit 70f6852

Browse files
committed
started working on docs for pax upgrade
1 parent 170bbb6 commit 70f6852

File tree

2 files changed

+141
-0
lines changed

2 files changed

+141
-0
lines changed
12.6 KB
Loading

docs/Cosmos-daemon/upgrade/upgrade.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
layout: default
3+
title: Upgrade Pax-daemon
4+
parent: CosmosDaemon
5+
---
6+
7+
# Upgrade paxd
8+
9+
A guide on how to updgrade the pax network.
10+
11+
## Cosmovisor
12+
13+
Cosmovisor is the recomended way to upgrade your validator node.
14+
More info on [Cosmosvisor](https://docs.cosmos.network/main/build/tooling/cosmovisor)
15+
16+
### Start Cosmovisor
17+
18+
Cosmosvisor is a wrapper around paxd that listens to upgrade planes being passed on the network. A upgrade plan contains a upgradeheigth and binary path.
19+
20+
Cosmosvisor will use the binary path to download the new binary if autoupdate has been passed in the starting arguments. This is not the recomendede way of doing it.
21+
22+
Recomended way of doing the upgrade is to download the new binary manuley and place it in the correct place in the cosmovisor folder structure
23+
24+
Cosmovisor sets up the folder strukture by its self.
25+
```
26+
.
27+
├── current -> genesis or upgrades/<name>
28+
├── genesis
29+
│   └── bin
30+
│   └── $DAEMON_NAME
31+
└── upgrades
32+
│ └── <name>
33+
│ ├── bin
34+
│ │   └── $DAEMON_NAME
35+
│ └── upgrade-info.json
36+
└── preupgrade.sh (optional)
37+
```
38+
39+
### Cosmovisor init
40+
Post v1 versions of Cosmovisor have a command that will create the directories and copy the `paxd` binary into the proper directory. To create the directories and copy the binary, run this command:
41+
42+
```
43+
cosmovisor init $HOME/go/bin/paxd
44+
```
45+
Once you're done, check the folder structure looks correct using a tool like `tree`.
46+
47+
### Cosmovisor config
48+
49+
In the .profile file, usually located at ~/.profile, add:
50+
51+
```
52+
export DAEMON_NAME=paxd
53+
export DAEMON_HOME=$HOME/.pax
54+
```
55+
Then source your profile to have access to these variables:
56+
57+
```
58+
source ~/.profile
59+
```
60+
You can confirm success like so:
61+
62+
```
63+
echo $DAEMON_NAME
64+
```
65+
It should return paxd.
66+
67+
`cosmovisor` reads its configuration from environment variables:
68+
69+
- `DAEMON_HOME` is the location where the `cosmovisor/` directory is kept that contains the genesis binary, the upgrade binaries, and any additional auxiliary files associated with each binary (e.g. `$HOME/.pax`, `$HOME/.unigrid`, etc.).
70+
- `DAEMON_NAME` is the name of the binary itself (e.g. `paxd`, etc.).
71+
- `DAEMON_ALLOW_DOWNLOAD_BINARIES` (_optional_), if set to `true`, will enable auto-downloading of new binaries (for security reasons, this is intended for full nodes rather than validators). By default, `cosmovisor` will not auto-download new binaries.
72+
- `DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM` (_optional_, default = `false`), if `true` cosmovisor will require that a checksum is provided in the upgrade plan for the binary to be downloaded. If `false`, cosmovisor will not require a checksum to be provided, but still check the checksum if one is provided.
73+
- `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`), `cosmovisor` stops running after an upgrade and requires the system administrator to manually restart it. Note restart is only after the upgrade and does not auto-restart the subprocess after an error occurs.
74+
- `DAEMON_RESTART_DELAY` (_optional_, default none), allow a node operator to define a delay between the node halt (for upgrade) and backup by the specified time. The value must be a duration (e.g. `1s`).
75+
- `DAEMON_SHUTDOWN_GRACE` (_optional_, default none), if set, send interrupt to binary and wait the specified time to allow for cleanup/cache flush to disk before sending the kill signal. The value must be a duration (e.g. `1s`).
76+
- `DAEMON_POLL_INTERVAL` (_optional_, default 300 milliseconds), is the interval length for polling the upgrade plan file. The value must be a duration (e.g. `1s`).
77+
- `DAEMON_DATA_BACKUP_DIR` option to set a custom backup directory. If not set, `DAEMON_HOME` is used.
78+
- `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 needed to rollback. We recommend using the default backup option `UNSAFE_SKIP_BACKUP=false`.
79+
- `DAEMON_PREUPGRADE_MAX_RETRIES` (defaults to `0`). The maximum number of times to call [pre-upgrade](https://docs.cosmos.network/main/build/building-apps/app-upgrade#pre-upgrade-handling) in the application after exit status of `31`. After the maximum number of retries, Cosmovisor fails the upgrade.
80+
- `COSMOVISOR_DISABLE_LOGS` (defaults to `false`). If set to true, this will disable Cosmovisor logs (but not the underlying process) completely. This may be useful, for example, when a Cosmovisor subcommand you are executing returns a valid JSON you are then parsing, as logs added by Cosmovisor make this output not a valid JSON.
81+
- `COSMOVISOR_COLOR_LOGS` (defaults to `true`). If set to true, this will colorise Cosmovisor logs (but not the underlying process).
82+
- `COSMOVISOR_TIMEFORMAT_LOGS` (defaults to `kitchen`). If set to a value (`layout|ansic|unixdate|rubydate|rfc822|rfc822z|rfc850|rfc1123|rfc1123z|rfc3339|rfc3339nano|kitchen`), this will add timestamp prefix to Cosmovisor logs (but not the underlying process).
83+
- `COSMOVISOR_CUSTOM_PREUPGRADE` (defaults to ``). If set, this will run $DAEMON_HOME/cosmovisor/$COSMOVISOR_CUSTOM_PREUPGRADE prior to upgrade with the arguments [ upgrade.Name, upgrade.Height ]. Executes a custom script (separate and prior to the chain daemon pre-upgrade command)
84+
- `COSMOVISOR_DISABLE_RECASE` (defaults to `false`). If set to true, the upgrade directory will expected to match the upgrade plan name without any case changes
85+
86+
## Set up service
87+
Commands sent to Cosmovisor are sent to the underlying binary. For example, `cosmovisor` version is the same as typing `paxd version`.
88+
89+
Nevertheless, just as we would manage `paxd` using a process manager, we would like to make sure Cosmovisor is automatically restarted if something happens, for example an error or reboot.
90+
91+
First, create the service file:
92+
93+
```
94+
sudo nano /etc/systemd/system/paxd.service
95+
````
96+
Change the contents of the below to match your setup - `cosmovisor` is likely at `~/go/bin/cosmovisor` regardless of which installation path you took above, but it's worth checking.
97+
98+
Note `cosmovisor run start` is only for the latest versions of cosmovisor. For earlier versions that line should be:
99+
100+
```
101+
ExecStart=/home/<your-user>/go/bin/cosmovisor start
102+
````
103+
```
104+
[Unit]
105+
Description=Pax Daemon (cosmovisor)
106+
After=network-online.target
107+
108+
[Service]
109+
User=<your-user>
110+
ExecStart=/home/<your-user>/go/bin/cosmovisor run start
111+
Restart=always
112+
RestartSec=3
113+
Environment="DAEMON_NAME=paxd"
114+
Environment="DAEMON_HOME=/home/<your-user>/.pax"
115+
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
116+
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
117+
Environment="DAEMON_LOG_BUFFER_SIZE=512"
118+
119+
[Install]
120+
WantedBy=multi-user.target
121+
```
122+
> A description of what the environment variables do can be found here. Change them depending on your setup.
123+
124+
125+
In addition, the same issue can be fixed by reducing the log via env variable. If you are unsure, ask on Discord.
126+
127+
## Modules
128+
129+
When doing an upgrade to a module do the following
130+
131+
### Create a new UpgradeHandler
132+
133+
When upgrading paxd you need to add a UpgradeHandler that handels state changes and initates new params.
134+
135+
Make a new folder under upgrades named the new version number.
136+
137+
![](../../../assets/images/pax_upgrade_folderStructure.png)
138+
139+
### Propose an upgrade
140+
141+
A upgrade is proposed and voted on. If the vote is passed it will trigger

0 commit comments

Comments
 (0)