English
How to update a Stakepool

โ€‹
๐ŸŽ‰
โˆž Pre-Announcements

โ€‹
๐ŸŽŠ
This latest update brought to you by the generous donations by BEBOP stake pool.
If you want to support this free educational Cardano content or found this helpful, visit cointr.ee to find our donation addresses. Much appreciated in advance.
๐Ÿ™
As of Oct 1 2021, this guide is written for mainnet with release v1.30.1
๐Ÿ˜

โ€‹
๐Ÿ“ก
1. How to perform an update

From time to time, there will be new versions of cardano-node. Follow the Official Cardano-Node Github Repo by enabling notifications with the watch functionality.
Read the patch notes for any other special updates or dependencies that may be required for the latest release.
v1.30.1 Notes
v1.29.0 Notes
v1.27.0 Notes
v1.26.2 Notes

โ€‹
๐Ÿ›‘
Release Dependencies

1. If using cncli for leaderlogs and sendslots, update to cncli version 4.0.1 is required.

1
RELEASETAG=$(curl -s https://api.github.com/repos/AndrewWestberg/cncli/releases/latest | jq -r .tag_name)
2
VERSION=$(echo ${RELEASETAG} | cut -c 2-)
3
echo "Installing release ${RELEASETAG}"
4
curl -sLJ https://github.com/AndrewWestberg/cncli/releases/download/${RELEASETAG}/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz -o /tmp/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz
Copied!
1
sudo tar xzvf /tmp/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz -C /usr/local/bin/
Copied!

Checking that cncli is properly updated

1
cncli -V
Copied!
It should return the updated version number.
2. Update gLiveView
1
cd ${NODE_HOME}
2
curl -s -o gLiveView.sh https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/gLiveView.sh
3
curl -s -o env https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/env
4
chmod 755 gLiveView.sh
5
# Update env file with the stake pools configuration.
6
sed -i env \
7
-e "s/\#CONFIG=\"\${CNODE_HOME}\/files\/config.json\"/CONFIG=\"\${NODE_HOME}\/mainnet-config.json\"/g" \
8
-e "s/\#SOCKET=\"\${CNODE_HOME}\/sockets\/node0.socket\"/SOCKET=\"\${NODE_HOME}\/db\/socket\"/g"
Copied!
This release is an important update to the node that provides the functionality that is needed following the Alonzo hard fork. All users, including stake pool operators, must upgrade to this version (or a later version) of the node.
The release includes features that will enable the use of the node in the Alonzo era, allowing the on-chain execution of Plutus scripts, including extended CLI commands to support the construction of transactions that include Plutus scripts, datums and redeemers. It incorporates several improvements, including a new transaction build command that calculates transaction fees and Plutus script execution units, and a new version of the query tip command that provides additional information, including node synchronisation progress. The transaction build command requires a local instance of the node in order to check Plutus script validity and to provide information that is used by the fee calculation. The Shelley specification has also been updated with respect to rewards calculation.
Note that this release changes the log format of traces configured by TraceChainSyncHeaderServer and TraceChainSyncClient . See #2746 for more detail.

โ€‹
๐Ÿ›‘
Release Dependencies

1. If using cncli for leaderlogs and sendslots, update to cncli version 3.15 is required.

1
RELEASETAG=$(curl -s https://api.github.com/repos/AndrewWestberg/cncli/releases/latest | jq -r .tag_name)
2
VERSION=$(echo ${RELEASETAG} | cut -c 2-)
3
echo "Installing release ${RELEASETAG}"
4
curl -sLJ https://github.com/AndrewWestberg/cncli/releases/download/${RELEASETAG}/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz -o /tmp/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz
Copied!
1
sudo tar xzvf /tmp/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz -C /usr/local/bin/
Copied!

Checking that cncli is properly updated

1
cncli -V
Copied!
It should return the updated version number.
2. Download mainnet-alonzo-genesis.json file
1
cd $NODE_HOME
2
wget -N https://hydra.iohk.io/build/7416228/download/1/mainnet-alonzo-genesis.json
Copied!
3. Download newmainnet-config.json file to with alonzo configurations.
If you have any custom mainnet configurations, be sure to backup and re-apply your settings.
1
cd $NODE_HOME
2
wget -N https://hydra.iohk.io/build/7416228/download/1/mainnet-config.json
3
sed -i mainnet-config.json \
4
-e "s/TraceBlockFetchDecisions\": false/TraceBlockFetchDecisions\": true/g" \
5
-e "s/127.0.0.1/0.0.0.0/g"
Copied!
Verify that your mainnet-config.json contains the following two new lines.
1
"AlonzoGenesisFile": "mainnet-alonzo-genesis.json",
2
"AlonzoGenesisHash": "7e94a15f55d1e82d10f09203fa1d40f8eede58fd8066542cf6566008068ed874",
Copied!
View your mainnet-config.json
1
cat mainnet-config.json
Copied!
Example of what it should look like with the two new lines.
1
{
2
"AlonzoGenesisFile": "mainnet-alonzo-genesis.json",
3
"AlonzoGenesisHash": "7e94a15f55d1e82d10f09203fa1d40f8eede58fd8066542cf6566008068ed874",
4
"ApplicationName": "cardano-sl",
5
"ApplicationVersion": 1,
6
"ByronGenesisFile": "byron-genesis.json",
7
"ByronGenesisHash": "5f20df933584822601f9e3f8c024eb5eb252fe8cefb24d1317dc3d432e940ebb",
8
"LastKnownBlockVersion-Alt": 0,
9
"LastKnownBlockVersion-Major": 3,
10
"LastKnownBlockVersion-Minor": 0,
11
"MaxKnownMajorProtocolVersion": 2,
12
"Protocol": "Cardano",
13
"RequiresNetworkMagic": "RequiresNoMagic",
14
"ShelleyGenesisFile": "genesis.json",
15
"ShelleyGenesisHash": "1a3be38bcbb7911969283716ad7aa550250226b76a61fc51cc9a9a35d9276d81",
Copied!
[ Optional Troubleshooting ] 4. In case your node does not start up properly, refresh mainnet-shelley-genesis.json
1
cd $NODE_HOME
2
wget -N https://hydra.iohk.io/build/7416228/download/1/mainnet-shelley-genesis.json
Copied!
Node version 1.27.0 provides important new functionality, including supporting new CLI commands that have been requested by stake pools, providing garbage collection metrics. It includes the performance fixes for the epoch boundary calculation that were released in node version 1.26.2, plus a number of bug fixes and code improvements. It also includes many fundamental changes that are needed to prepare for forthcoming feature releases (notably Plutus scripts in the Alonzo era). Note that this release includes breaking changes to the API and CLI commands, and that compilation using GHC version 8.6.5 is no longer supported.

โ€‹
๐Ÿ›‘
Release Dependencies

1. If using cncli for leaderlogs and sendslots, update to cncli version 2.10 is required.

1
RELEASETAG=$(curl -s https://api.github.com/repos/AndrewWestberg/cncli/releases/latest | jq -r .tag_name)
2
VERSION=$(echo ${RELEASETAG} | cut -c 2-)
3
echo "Installing release ${RELEASETAG}"
4
curl -sLJ https://github.com/AndrewWestberg/cncli/releases/download/${RELEASETAG}/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz -o /tmp/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz
Copied!
1
sudo tar xzvf /tmp/cncli-${VERSION}-x86_64-unknown-linux-gnu.tar.gz -C /usr/local/bin/
Copied!

Checking that cncli is properly updated

1
cncli -V
Copied!
It should return the updated version number.
This point release is a recommended upgrade for all stake pool operators. It is not required for relays or other passive nodes. It ensures that block producing nodes do not unnecessarily re-evaluate the stake distribution at the epoch boundary.
It is possible to upgrade from v1.25.1 but for a smooth update, ensure you have completed the v1.26.1 release dependencies, notably the ghc and cabal updates. Also note the database migration can take up to 2 hours.

Compiling the new binaries

To update with $HOME/git/cardano-node as the current binaries directory, clone a new git repo named cardano-node2 so that you have a backup in case of rollback. Remove the old binaries.
1
cd $HOME/git
2
rm -rf cardano-node-old/
3
git clone https://github.com/input-output-hk/cardano-node.git cardano-node2
4
cd cardano-node2/
Copied!
Run the following command to pull and build the latest binaries. Change the checkout tag or branch as needed.
1
cd $HOME/git/cardano-node2
2
cabal update
3
git fetch --all --recurse-submodules --tags
4
git checkout $(curl -s https://api.github.com/repos/input-output-hk/cardano-node/releases/latest | jq -r .tag_name)
5
cabal configure -O0 -w ghc-8.10.4
6
echo -e "package cardano-crypto-praos\n flags: -external-libsodium-vrf" > cabal.project.local
7
cabal build cardano-node cardano-cli
Copied!
Build process may take a few minutes up to a few hours depending on your computer's processing power.
Verify your cardano-cli and cardano-node were updated to the expected version.
1
$(find $HOME/git/cardano-node2/dist-newstyle/build -type f -name "cardano-cli") version
2
$(find $HOME/git/cardano-node2/dist-newstyle/build -type f -name "cardano-node") version
Copied!
Stop your node before updating the binaries.
systemd
cnode
block producer node
relaynode1
1
sudo systemctl stop cardano-node
Copied!
1
sudo systemctl stop cnode
Copied!
1
killall -s 2 cardano-node
Copied!
1
killall -s 2 cardano-node
Copied!
Copy cardano-cli and cardano-node files into bin directory.
1
sudo cp $(find $HOME/git/cardano-node2/dist-newstyle/build -type f -name "cardano-cli") /usr/local/bin/cardano-cli
Copied!
1
sudo cp $(find $HOME/git/cardano-node2/dist-newstyle/build -type f -name "cardano-node") /usr/local/bin/cardano-node
Copied!
Verify your cardano-cli and cardano-node were copied successfully and updated to the expected version.
1
cardano-node version
2
cardano-cli version
Copied!
Optional Best Practice: Now is an opportune time to update/upgrade and reboot your Ubuntu operating system.
1
sudo apt-get update && sudo apt-get upgrade -y && sudo reboot
Copied!
Now restart your node to use the updated binaries. If you used the previously mentioned optional best practice, your binaries should've already auto-started.
systemd
cnode
block producer node
relaynode1
1
sudo systemctl start cardano-node
Copied!
1
sudo systemctl start cnode
Copied!
1
cd $NODE_HOME
2
./startBlockProducingNode.sh
Copied!
1
cd $NODE_HOME
2
./startRelayNode1.sh
Copied!
Finally, the following sequence will switch-over to your newly built cardano-node folder while keeping the old directory for backup.
1
cd $HOME/git
2
mv cardano-node/ cardano-node-old/
3
mv cardano-node2/ cardano-node/
Copied!
Verify that your node is working successfully by either checking gLiveView, your other journalctl logs, or grafana dashboard.
gLiveView
journalctl
1
cd ${NODE_HOME}
2
./gLiveView.sh
Copied!
1
journalctl -fu cardano-node
Copied!
It may take some time to start a node, sometimes up to 30 minutes. gLiveView may appear stuck on "Starting..." but this is normal behavior and simply requires time.
โ€‹
๐Ÿค–
Important Reminder: Don't forget to update your air-gapped offline machine (cold environment) with the new Cardano CLI binaries.
Congrats on completing the update.
โœจ
Did you find our guide useful? Send us a signal with a tip and we'll keep updating it.
It really energizes us to keep creating the best crypto guides.
Use cointr.ee to find our donation addresses.
๐Ÿ™
Any feedback and all pull requests much appreciated.
๐ŸŒ›
Hang out and chat with fellow stake pool operators on Discord @
Hang out and chat with our stake pool community on Telegram @ https://t.me/coincashewโ€‹

โ€‹
๐Ÿคฏ
2. In case of problems

โ€‹
๐Ÿ›ฃ
4.1 Forked off

Forget to update your node and now your node is stuck on an old chain?
Reset your database files and be sure to grab the latest genesis, config, topology json files.
1
cd $NODE_HOME
2
rm -rf db
Copied!

โ€‹
๐Ÿ“‚
4.2 Roll back to previous version from backup

Stop your node before updating the binaries.
systemd
cnode
block producer node
relaynode1
1
sudo systemctl stop cardano-node
Copied!
1
sudo systemctl stop cnode
Copied!
1
killall -s 2 cardano-node
Copied!
1
killall -s 2 cardano-node
Copied!
Restore the old repository.
1
cd $HOME/git
2
mv cardano-node/ cardano-node-rolled-back/
3
mv cardano-node-old/ cardano-node/
Copied!
Copy the binaries to /usr/local/bin
1
sudo cp $(find $HOME/git/cardano-node/dist-newstyle/build -type f -name "cardano-cli") /usr/local/bin/cardano-cli
2
sudo cp $(find $HOME/git/cardano-node/dist-newstyle/build -type f -name "cardano-node") /usr/local/bin/cardano-node
Copied!
Verify the binaries are the correct version.
1
/usr/local/bin/cardano-cli version
2
/usr/local/bin/cardano-node version
Copied!
Now restart your node to use the updated binaries.
systemd
cnode
block producer node
relaynode1
1
sudo systemctl start cardano-node
Copied!
1
sudo systemctl start cnode
Copied!
1
cd $NODE_HOME
2
./startBlockProducingNode.sh
Copied!
1
cd $NODE_HOME
2
./startRelayNode1.sh
Copied!

โ€‹
๐Ÿค–
4.3 Last resort: Rebuild from source code

Follow the steps in How to build a Stakepool.โ€‹
Last modified 2mo ago