Installing a Radix Node Docker Instance with the CLI

Introduction

Using the radixnode CLI tool, you can proceed to installing the node, performing initial setup, and starting it up. While the CLI supports running the node as either a Docker instance or a systemd install using systemd, we recommend Docker as the more straightforward and easy to maintain method.

1. Install Docker

This is done through one simple call of the radixnode CLI script:

radixnode docker configure

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

Exit ssh login and relogin back for user addition to group "docker" to take effect

2. Install the node

Execute the following command to install the node:

  1. Run the following command, paying close attention to the parameters

    • full node

    • archive node

    radixnode docker setup \
        -n fullnode \    (1)
        -u \    (2)
        -t [address@IP of chosen seed node]     (3)
    radixnode docker setup \
        -n archivenode \    (1)
        -u \    (2)
        -t [address@IP of chosen seed node]     (3)
    1 The -n option sets the node type, which can be fullnode or archivenode.
    2 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 The -t setting is the validator address and IP of a seed node that your node will 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 seed node from the list below:
    Asia Pacific (south-east)
    radix://rn1q2jt0jswv3lpct8tavr5tvlg2kv25f26x7w8kf6dz2hp4pu9cwq4we9tm5f@13.238.198.54
    radix://rn1qvmp586ylq9e26n98zwyu9s5hdkq8j63t8l028x8wj4vqzk32dwzw0vrg58@54.66.161.181
    radix://rn1q2fqfp9smlv3x5j4gca400j3mg9q63pgpu8hmd0xs0a3dgw5mv5s6jgznp3@3.106.155.92
    radix://rn1qvcrg55mcgx6qgs7hj5arpvakvyzpc9pnp5ywhgcs4mvmp7ee4846p5zsdg@54.79.170.237
    Asia Pacific (south)
    radix://rn1qg54vufz29c5hcwqxuv4pr60f4fsq6ds0qpa7qnrchdwnapkw6qcxymhy7l@3.109.57.223
    radix://rn1qgf0tug4nmxfa7su8zsu8pejzq48eeglvxf8le09cuy0nsghzg44weacz2q@3.109.36.249
    radix://rn1qfcl8ml7vm2gnyvm6tslmemrjmds6apajrk3vvyl4the0wsm0mkvjrjgtl2@65.0.241.14
    radix://rn1qd4nnpfkafpljwt8xmvk5ksqy6cn7n3j6t2pcqrx4p2h6drt9qqksn8m94r@3.108.213.235
    EU (west)
    radix://rn1qthu8yn06k75dnwpkysyl8smtwn0v4xy29auzjlcrw7vgduxvnwnst6derj@99.80.126.26
    radix://rn1qtk3g0a2ra663wyua0l4720vfzdje9uqsdzgzjet5w9dhspkaywnjal6dv6@52.49.146.20
    radix://rn1qgvg5c20ude9cwxuxenrltemtw5zsg6n879kguwy0cx4mzq5plqg532l2xf@34.242.56.73
    radix://rn1q040l0vqzuglnj6t5ffue3nacnj30h0thyrses0f5cc0n2fvx4wtknv2t7y@54.74.152.104
    US (east)
    radix://rn1qvw5v4w8llexz99uc9gmeh47qp2h9ax2y3aewm5e6vj5sdx8uuph2vfuvg3@3.221.232.135
    radix://rn1qtq336a2nn2269fjes53pynwlytrv0katm6uzlfcyl6m7yscac5g7mh8prw@3.220.101.80
    radix://rn1qwa45jjf40vuf9xlq85xym86yegnm95h3g8d4lul5hskrws9gm6ykyx7hsf@3.214.160.245
    radix://rn1qvv0uljlqdsmed4kwjqr56sqkgcl8jer3z7w68ssfele3e4cz6uzugfjf0h@44.194.199.37

While running, the CLI will report on its progress, asking at various stages if it is okay to continue; answer Y each time if you’re happy to proceed.

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

To continue running the script successfully, you must log out of the session and log in again.

3. 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 The Radix Node API.)

3.1. Set the admin password for the Nginx server

This will set up the admin user and password for access to the general system endpoints.

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

    radixnode auth set-admin-password --setupmode DOCKER
  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
  4. Add the new environment variable to your session by executing the following command:

    source ~/.bashrc

3.2. Set the super admin password for the Nginx server

You will also need to set up access to the /account endpoint which is used to retrieve information about the node.

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

    radixnode auth set-superadmin-password --setupmode DOCKER
  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_SUPERADMIN_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. Nginx user endpoints
Nginx user Service endpoints

superadmin

/account

admin

/system
/validation
/health
/version

metrics

/metrics

no user required

/archive
/construction

4. Install and start up the Docker node

With the Docker and Nginx installed and configured, we are ready to install the node as a Docker instance.

The CLI installs, configures, and starts up the node all in one step. The most important choice you must make at this step is what type of node you wish to operate. As described in the introduction to Radix Nodes, there are three types of node depending on its intended purpose: full node, validator node, or archive node.

When starting up your node, will choose fullnode or archivenode. A validator node is simply a full nodes that has been registered to the Radix network as valiadtor – a step that is covered later – so choose fullnode for either a full node or validator node. archivenode enables the substantial indexing of on-ledger data required to offer the archive node’s additional API capabilities.

Run the following command to start your node:

  • full node

  • archive node

radixnode docker setup  \
     -n fullnode \      (1)
     -r 1.0.0 \   (2)
     -t [address@IP of chosen seed node]    (3)
radixnode docker setup  \
     -n archivenode \      (1)
     -r 1.0.0 \   (2)
     -t [address@IP of chosen seed node]    (3)
1 The -n option sets the node type, which can be either fullnode or archivenode.
2 The -r option is optional and specifies the release of the node software you wish to install. If not provided it will use the latest release from https://github.com/radixdlt/radixdlt/releases.
3 t is the address of the seed node that your node will use to join the network. Use the same address that you used in Section 1, “Install Docker”

In the setup process, the CLI will create a new node-keystore.ks file and ask you for a password to protect it.

The key generation process may take a long time if your server hasn’t generated a sufficiently large pool of random values to build fresh keys. Be prepared to wait up to twenty minutes for the key generation to complete.

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.

Now that your Docker node should be running, there are some basic commands offered by radixnode to check on your node’s operation.

5. Make sure the node is running

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

radixnode api account get-info

This command will show you the address, along with the number of tokens held by the node:

{"result": {"address": "rdx1qspl7mgjqwgwqyjvy2tj8swe8a4lr6mxqdhwmn60cujl6a85mqh69eg37p9ph", "balance": {"stakes": [], "tokens": []}}, "id": 1, "jsonrpc": "2.0"}

6. Check your node is syncing correctly

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

radixnode api version

or the node’s status:

radixnode api health

This will return a message like this:

{"status": "UP"}

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

More information on radixnode Usage

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

You can find more information about the RadixNode 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.