Upgrade a node

The node installer pins the supported Rusk and Rusk Wallet versions for each network. Rerunning it downloads and verifies replacement binaries before stopping the current Rusk service.

Keep the same role

Repeat the network and feature flags used for the existing node. Omitting --feature archive replaces an archive installation with the default Rusk binary.

Before upgrading

Record the current state:

ruskquery version
ruskquery info | jq '{version, chain_id, kadcast_address}'
ruskquery peers
ruskquery block-height
systemctl is-active rusk

Retain a secure copy of consensus keys and intentional configuration. The installer preserves:

• /opt/dusk/conf/consensus.keys;
• /opt/dusk/services/dusk.conf;
• /opt/dusk/services/rusk.conf.user; and
• chain state under /opt/dusk/rusk.

It regenerates /opt/dusk/conf/rusk.toml, genesis.toml, the Rusk systemd unit, managed binaries and scripts, and the selected user’s wallet configuration. Save the old rusk.toml for comparison if it contains intentional changes, but do not copy it over the new network configuration wholesale.

Run the installer

Choose the command matching the node.

Mainnet provisioner or full node

curl --proto '=https' --tlsv1.2 -sSfL \
  https://github.com/dusk-network/node-installer/releases/latest/download/node-installer.sh \
  | sudo bash

Mainnet archive node

curl --proto '=https' --tlsv1.2 -sSfL \
  https://github.com/dusk-network/node-installer/releases/latest/download/node-installer.sh \
  | sudo bash -s -- --feature archive

Testnet provisioner or full node

curl --proto '=https' --tlsv1.2 -sSfL \
  https://github.com/dusk-network/node-installer/releases/latest/download/node-installer.sh \
  | sudo bash -s -- --network testnet

Testnet archive node

curl --proto '=https' --tlsv1.2 -sSfL \
  https://github.com/dusk-network/node-installer/releases/latest/download/node-installer.sh \
  | sudo bash -s -- --network testnet --feature archive

When an automation process runs the installer directly as root, append --user <operator-user> so the wallet configuration is written to the intended home directory. A normal interactive sudo invocation uses SUDO_USER automatically.

The installer stops Rusk only after downloads and binary version checks pass. It enables and reloads the systemd unit, but leaves Rusk stopped.

Review and restart

If the previous rusk.toml contained intentional operator settings, compare it with the generated file and reapply only the required values. Archive API operators commonly need to restore their [http] configuration.

Start the service:

sudo systemctl start rusk

Then verify all layers:

systemctl is-active rusk
systemctl show rusk -p ActiveState -p SubState -p NRestarts
ruskquery info | jq '{version, chain_id, kadcast_address}'
ruskquery peers
ruskquery block-height
sudo tail -n 50 /var/log/rusk.log

Check the height again after roughly 30 seconds and compare it with the matching network explorer or public endpoint. For an archive node, also run an archive GraphQL query before returning API traffic to it.

If Rusk fails to start, inspect:

sudo systemctl status rusk --no-pager
sudo journalctl -u rusk --since "15 minutes ago" --no-pager
sudo tail -n 100 /var/log/rusk_recovery.log

Do not repeatedly rerun the installer until the first failure is understood. See Troubleshooting and Roll back a node update when appropriate.

Testnet resets

Testnet can be reset independently of mainnet. Follow an announced reset by reinstalling with --network testnet, then use the supported fast-sync or reset procedure specified in the announcement. Do not reset state merely because a normal upgrade temporarily lags the network.