> ## Documentation Index
> Fetch the complete documentation index at: https://docs.story.foundation/llms.txt
> Use this file to discover all available pages before exploring further.

# Node Upgrade

> Guide to upgrading your Story node clients

There are three types of upgrades

1. Upgrade the story geth client
2. Upgrade the story client manually
3. Schedule the upgrade with Cosmovisor

### Upgrade the story geth client

```bash theme={null}
# Stop the services
sudo systemctl stop story
sudo systemctl stop story-geth

# Download the new binary
wget ${STORY_GETH_BINARY_URL}
sudo mv ./geth-linux-amd64 story-geth
sudo chmod +x story-geth
sudo mv ./story-geth $HOME/go/bin/story-geth
source $HOME/.bashrc

# Restart the service
sudo systemctl start story-geth
sudo systemctl start story
```

### Upgrade the story client manually

```bash theme={null}
# Stop the service
sudo systemctl stop story

# Download the new binary
wget ${STORY_BINARY_URL}
sudo mv story-linux-amd64 story
sudo chmod +x story
sudo mv ./story $HOME/go/bin/story

# Schedule the update
sudo systemctl start story
```

### Schedule the upgrade with Cosmovisor

The following steps outline how to schedule an upgrade using Cosmovisor:

1. Create the upgrade directory and download the new binary

```bash theme={null}
# Download the new binary
wget ${STORY_BINARY_URL}

# Schedule the upgrade
source $HOME/.bash_profile
cosmovisor add-upgrade ${UPGRADE_NAME} ${UPGRADE_PATH} \
  --force \
  --upgrade-height ${UPGRADE_HEIGHT}
```

2. Verify the upgrade configuration

```bash theme={null}
# Check the upgrade info
cat $HOME/.story/story/data/upgrade-info.json
```

The upgrade-info.json should show:

```json theme={null}
{
  "name": "v1.0.0",
  "time": "2025-02-05T12:00:00Z",
  "height": 858000
}
```

3. Monitor the upgrade

```bash theme={null}
# Watch the node logs for the upgrade
journalctl -u story -f -o cat
```

Note: Cosmovisor will automatically handle the binary switch once the specified block height is reached. Before the upgrade, confirm that your node is fully synced and has enough disk space available.

### Use Cosmovisor While running Story Node

This guide is for people who are running story without using cosmovisor, but still want to use cosmovisor to schedule the upgrade.

1. Install Cosmovisor

```bash theme={null}
# Install Cosmovisor
go install github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@1.6.0

cosmovisor version
```

You will see the version of cosmovisor.

```
cosmovisor version: v1.6.0
Error: failed to run version command: DAEMON_NAME is not set
DAEMON_HOME is not set
DAEMON_DATA_BACKUP_DIR must not be empty
```

2. Set the environment variables

```bash theme={null}
# Set daemon configuration
export DAEMON_NAME=story
export DAEMON_HOME=$HOME/.story/story
export DAEMON_DATA_BACKUP_DIR=${DAEMON_HOME}/cosmovisor/backup
sudo mkdir -p $DAEMON_HOME/cosmovisor/backup $DAEMON_HOME/data


# Persist configuration
echo "export DAEMON_NAME=story" >> $HOME/.bash_profile
echo "export DAEMON_HOME=$HOME/.story/story" >> $HOME/.bash_profile
echo "export DAEMON_DATA_BACKUP_DIR=${DAEMON_HOME}/cosmovisor/backup" >> $HOME/.bash_profile
echo "export DAEMON_ALLOW_DOWNLOAD_BINARIES=false" >> $HOME/.bash_profile
```

If you have any permission issues, you can run the following command to fix it.

```bash theme={null}
sudo chown -R $USER:$USER $HOME/.story
```

3. Setup the cosmovisor

```bash theme={null}
# Create the cosmovisor directory
mkdir -p $HOME/.story/cosmovisor/genesis/bin

# Copy the new binary to the cosmovisor directory
cp $HOME/go/bin/story $HOME/.story/cosmovisor/genesis/bin/
```

4. Add cosmovisor to the systemd service

```bash theme={null}
sudo tee /etc/systemd/system/cosmovisor.service > /dev/null <<EOF
[Unit]
Description=Cosmovisor
After=network.target

[Service]
Type=simple
User=$USER
Group=$GROUP
ExecStart=${which cosmovisor} run run \
--api-enable \
--api-address=${API_ADDRESS}
Restart=on-failure
RestartSec=5s
LimitNOFILE=65535
Environment="DAEMON_NAME=$DAEMON_NAME"
Environment="DAEMON_HOME=$DAEMON_HOME"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_DATA_BACKUP_DIR=$DAEMON_HOME/cosmovisor/backup"
WorkingDirectory=$DAEMON_HOME

[Install]
WantedBy=multi-user.target
EOF
```

```bash theme={null}
# Enable the cosmovisor service
sudo systemctl enable cosmovisor
sudo systemctl daemon-reload

sudo systemctl stop story


# Start the cosmovisor service
sudo systemctl start cosmovisor

# Check the status of the cosmovisor service
sudo systemctl status cosmovisor

sudo journalctl -u cosmovisor -f -o cat
```

Check the status of the cosmovisor service

```bash theme={null}
cosmovisor version
```

You will see the version of cosmovisor.

```bash theme={null}
cosmovisor version: v1.6.0
12:16AM INF running app args=["version"] module=cosmovisor path=${DAEMON_HOME}/cosmovisor/genesis/bin/story
Version       v1.1.3-stable
Git Commit    38313e8
Git Timestamp 2025-04-11T04:24:27Z
```

5. Schedule the upgrade

```bash theme={null}
# Download the new binary
wget ${STORY_BINARY_URL}

# Schedule the upgrade
source $HOME/.bash_profile
cosmovisor add-upgrade ${UPGRADE_NAME} ${UPGRADE_PATH} \
  --force \
  --upgrade-height ${UPGRADE_HEIGHT}
```