Installing a Radix Node with the CLI

These instructions are for installing just a validator or full node with the CLI.

Introduction

Using the babylonnode CLI tool, you can install dependencies, configure your node installation, and then install and start up your node.

The CLI supports running the node either using Docker, or via systemd. However, we recommend Docker as the more straightforward and easy-to-maintain method.

The CLI currently only supports the Ubuntu operating system. We recommend the following hardware specification as a minimum starting point.

Model vCPU Memory (GB) Storage(GB) Network Bandwidth (Gbps) Operating System

c5.2xlarge

8

16

Provision a gp2 storage volume.

You should initially provision 250 GB of SSD space

Up to 10

Ubuntu 22.04.2.0 LTS (Jammy Jellyfish)

You should initially provision 250 GB of SSD space

1. Install the CLI

If you haven’t done so already, follow the instructions to install the Node CLI here.

2. Install dependencies on the host machine

This is required only to be run during first time setup on a new host machine. This is done through one simple call of the babylonnode CLI script.

  • docker mode

  • systemd mode

babylonnode docker dependencies

Once the process has completed, you will be asked to log out of your ssh bash session and log back in.

babylonnode systemd dependencies

The script will install the software necessary for systemd mode. You’ll be asked to create a password for the radixdlt user. (For security, the node runs under the radixdlt user, rather than running as an administrator).

Once you have entered and confirmed the password, you will be presented with a series of instructions to enable the radixdlt user to execute commands without the need for user intervention.

Execute following commands so that the radixdlt user can use sudo commands without needing you to enter a password:

  $ sudo su

  $ echo "radixdlt ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/radixdlt

3. Install the node

3.1. Create the config file

From version 1.3.2 onwards, the CLI supports a two-phase config/install setup for docker nodes and gateways. First, you are lead through an interactive prompt to create a config.yaml file, which by default is stored at ~/babylon-node-config/config.yaml. This config file is then used for future installs and upgrades, to avoid having to remember your settings later.

If you want to setup in systemd mode, this does not yet support the two phase config/install, so you should skip straight to the single phase install command.

A KeyStore is created during the config command, and the password that was entered is written to the generated config.yaml file. If you wish, you can delete the line containing keystore_password, but ensure you store the keystore password value safely, as it will be required in a later step.

The key file contains a randomly-generated private key that determines your node’s unique address and (if choosing to register as a validator node) validator ID.

This means if you lose your key file, you will forever lose your node address and validator ID - forcing you to generate a new key file from scratch.

Any tokens held by the node address will be lost.

As a validator, your delegators will have to unstake from your validator ID and restake to your new ID.

Always make sure that you securely back up your key file as soon as you’ve generated it, and carefully protect it.

  • docker mode

  • systemd mode

The config command has two modes for node setup.

If you are running a node for the first time, we recommend using the CORE mode. If you are already running an existing node using docker, you will need to use the DETAILED mode to migrate the setup, as it allows you to create a config file based on the answers that you have from existing setup.

CORE - This is a quick config mode to create a config file with simple defaults to run a full node for Core API support.

babylonnode docker config -m CORE

DETAILED - This is a detailed config mode, where the user is asked all necessary questions based on the answers replied.

babylonnode docker config -m DETAILED

The config file is created from the input. It will be used during the installation command. At default you can find it at ~/babylon-node-config/config.yaml.

CORE - This is a quick config mode to create a config file with simple defaults to run a full node for Core API support.

babylonnode systemd config -m CORE

DETAILED - This is a detailed config mode, where the user is asked all necessary questions based on the answers replied.

babylonnode systemd config -m DETAILED

The config file is created from the input. It will be used during the installation command. At default you can find it at ~/babylon-node-config/config.yaml.

  • Mainnet Seed Nodes

  • Stokenet Seed Nodes

radix://node_rdx1qf2x63qx4jdaxj83kkw2yytehvvmu6r2xll5gcp6c9rancmrfsgfw0vnc65@52.212.35.209,radix://node_rdx1qgxn3eeldj33kd98ha6wkjgk4k77z6xm0dv7mwnrkefknjcqsvhuu4gc609@54.79.136.139,radix://node_rdx1qwrrnhzfu99fg3yqgk3ut9vev2pdssv7hxhff80msjmmcj968487uugc0t2@43.204.226.50,radix://node_rdx1q0gnmwv0fmcp7ecq0znff7yzrt7ggwrp47sa9pssgyvrnl75tvxmvj78u7t@52.21.106.232
radix://node_tdx_2_1qv89yg0la2jt429vqp8sxtpg95hj637gards67gpgqy2vuvwe4s5ss0va2y@13.126.248.88,radix://node_tdx_2_1qvtd9ffdhxyg7meqggr2ezsdfgjre5aqs6jwk5amdhjg86xhurgn5c79t9t@13.210.209.103,radix://node_tdx_2_1qwfh2nn0zx8cut5fqfz6n7pau2f7vdyl89mypldnn4fwlhaeg2tvunp8s8h@54.229.126.97,radix://node_tdx_2_1qwz237kqdpct5l3yjhmna66uxja2ymrf3x6hh528ng3gtvnwndtn5rsrad4@3.210.187.161

3.2. Install and setup node

Run the following command and pay close attention to parameters:

  • docker mode

  • systemd mode

babylonnode docker install
  1. Optional - Use parameter -f <path to config.yaml> if the config file is different from the /home/ubunu/babylon-node-config/config.yaml.

  2. Optional - Use paramter -a or --autoapprove to run this command without any prompts. It is only recommended for automation purpose.

  3. Use parameter -u or --update to deploy latest versions of software.

  1. Log in as radixdlt

    sudo su - radixdlt
  2. Then ensure that you are in the /home/radixdlt directory. You can check your current directory using the following command:

    pwd

    If you’re not in the /home/radixdlt directory then switch to it:

    cd /home/radixdlt
  3. Run the following command, paying close attention to the parameters

babylonnode systemd install
  1. Optional - The -i option is the external IP address of your server.

  2. Optional - The -u flag is optional and is used only if you are upgrading from a previous version of the node. If applied to the command, it will create a backup of the old configuration file and ensure that the node has stopped before applying the changes.

  3. Optional - The -t setting is the address of a Radix node you can use to join the network. When the command executes, the script will download the configuration file from the specified node and attempt to make a connection. Select your closest node from the list of seed nodes.

4. Set passwords for the Nginx server

To keep the node as secure possible, the API is divided across a number of different endpoints to allow for varying levels of access to the node’s functions. This requires different usernames and passwords for each endpoint. (If you want more information about the Radix Node API, then take a look at Introduction to Radix APIs.)

  1. Execute the following command to set the password for the nginx web server:

    • docker mode

    • systemd mode

    Basic Auth User

    Command to run

    admin

    babylonnode auth set-admin-password --setupmode DOCKER

    superadmin

    babylonnode auth set-superadmin-password --setupmode DOCKER

    metrics

    babylonnode auth set-metrics-password --setupmode DOCKER

    Basic Auth User

    Command to run

    admin

    babylonnode auth set-admin-password --setupmode SYSTEMD

    superadmin

    babylonnode auth set-superadmin-password --setupmode SYSTEMD

    metrics

    babylonnode auth set-metrics-password --setupmode SYSTEMD
  2. Enter your password at the prompt, then enter it again at the verification prompt.

  3. As shown on screen, enter the following command to set an environment variable for your password (remember to fill in your own password):

    echo 'export NGINX_ADMIN_PASSWORD="nginx-password"' >> ~/.bashrc
    echo 'export NGINX_SUPERADMIN_PASSWORD="nginx-password"' >> ~/.bashrc
    echo 'export NGINX_METRICS_PASSWORD="nginx-password"' >> ~/.bashrc
  4. Add the new environment variable to your session by executing the following command:

    source ~/.bashrc

To keep the node as secure as possible, there are separate nginx usernames/passwords for each functionally-related enpoint.

Table 1. Radix Node endpoints
Nginx user Service endpoints

admin

/core/*
/system/*

metrics

/prometheus/metrics

5. Make sure the node is running

You can check to see if your node is running by checking for its identifiers:

 babylonnode api system identity

This command will show you the identifiers as below for the key on your node

Command output
{
"public_key_hex": "026d1c2b05398bd3f99ee0996bf972529fb50cbaec80feafc7e38094bfba50466f",
"node_address": "node_tdx_22_1qfk3c2c98x9a87v7uzvkh7tj220m2r96ajq0at78uwqff0a62prx70aukfx",
"node_uri": "radix://node_tdx_22_1qfk3c2c98x9a87v7uzvkh7tj220m2r96ajq0at78uwqff0a62prx70aukfx@3.8.118.228:30000",
"node_name": "no...rx70aukfx",
"node_id": "NodeId[026d1c2b05398bd3f99ee0996bf972529fb50cbaec80feafc7e38094bfba50466f]",
"validator_name": "026d1c2b05",
"consensus_status": "NOT_CONFIGURED_AS_VALIDATOR"
}

6. Check your node is syncing correctly

The babylonnode script allows you to interrogate your node for useful information, such as the software version:

babylonnode api system version

or the node’s status:

babylonnode api system health

This will return a message like this:

Command output
{
  "status": "UP",
  "current_fork_name": "SomeForkName",
  "executed_forks": [

  ],
  "fork_vote_status": "NO_ACTION_NEEDED",
  "unknown_reported_forks": [

  ]
}

An UP status means the node is running and syncing with the network correctly. Details on the other status codes can be found in Monitoring your node’s health

7. Stopping your node

This command will shut down a systemd or docker node, and is executed differently depending on which kind of installation you’re running.

  • docker

  • systemd

babylonnode docker stop

Optional parameter -f can be used to point to config.yaml file

babylonnode systemd stop

Optional parameter -f can be used to point to config.yaml file

8. Restarting your node

Restart the node using the following command:

  • docker

  • systemd

babylonnode docker start

Optional parameter -f can be used to point to config.yaml file

babylonnode systemd restart

Optional parameter -f can be used to point to config.yaml file

9. Advanced usage - Changing node parameters

Once you are satisfied that your node is running correctly, you can change the parameters.

You should not change the node’s default settings unless you are confident as to what each setting does and how changing it will affect the operation of your node

10. Advanced user config

For advanced users, there is an additional file that can be optionally mounted to provide additional configuration to the babylon-node application which will be appended to the configuration when executing the install command. This allows to add configuration that the nodecli does not natively support.

This file is located by default at ~/babylon-node-config/advanced-user.env-file for docker and at ~/babylon-node-config/advanceduserconfig for systemd. The file will be picked up when executing install without needing to rerun the config command.

10.1. Advanced user config - Docker

Additional environment variables can be added by creating the file ~/babylon-node-config/advanced-user.env-file and writing environment variables in the format described here.

A file from a different location can be used during the install command by providing the option -aue or --advanceduserenvs followed with the desired location.

Refer to the default.config substition file to find out what variables will be converted to which config parameters.

Please note that the file will only be mounted when executing install while the file is present at ~/babylon-node-config/advanced-user.env-file or the provided custom path.

10.2. Advanced user config - Systemd

Additional configurations can be provided by creating a file at ~/babylon-node-config/advanceduserconfig and adding plain configuration to it. This configuration will be appended to the default.config file during templating when executing the install command.

A file from a different location can be used during the install command by providing the option -auc or --advanceduserconfig followed with the desired location.

Refer to the default.config substition file to find out the format and supported variables.

Please note that the file and changes to it will not be added when running start, restart or stop but only when executing the install command while the file at ~/babylon-node-config/advanceduserconfig or the provided custom location is present.

More information on babylonnode Usage

You can use babylonnode to carry out a variety of administration tasks. For example:

You can find more information about the babylonnode CLI command set here.

If you have any questions or run into problems, then check our troubleshooting guide, or the Node FAQ page. You can also get support from the Radix community and Radix team members.