Provisioning a Docker Node with the RadixNode CLI


RadixDLT are launching a new Python-base installation which takes much of the boilerplate out of getting your Radix node up and running. Once installed, Node Runner will support the following functions:

  • Install or upgrade a full Radix Node as a Docker instance.

  • Convert a full node to a validator node.

  • Configure the node for dashboard monitoring.

This guide shows how to create a Docker node. Once complete, you can continue on to Registering a Validator Node using the RadixNode CLI, but make sure you complete this exercise first.

This script has only been tested on Linux Ubuntu 20.04

Windows is not supported


We’re assuming you’re familiar with Unix-based operating systems. Your hardware profile should match or exceed the following specification:

CPUs Memory (GB) Storage(GB) Network Bandwidth (Gbps) Operating System



100 GB of SSD space (initially)

Up to 10

Ubuntu LTS (Focal Fossa)

If you’re upgrading an existing node then remember to make a copy of your validator.ks file before you continue.

1. Update Packages

Ensure that all the packages on the system are up to date by running the following command from the terminal

sudo apt update -y

You will also need to install wget which you’ll need for downloading the radixnode script.

sudo apt install wget
This might be installed already as a standard package on your system.

2. Download the radixnode script.

The radixnode script can be downloaded from the RadixDLT GitHub repository.

  1. Go to the URL and look for the entry with the Latest release marker.

  2. Copy the link for the latest release of radixnode.

  3. Add the link to a wget command to download the file:

    wget -O radixnode
  4. Set the permissions on the script to executable.

    chmod +x radixnode
  5. Now move it to the /usr/local/bin/ directory, so it’s accessible from any other directory.

    sudo mv radixnode /usr/local/bin

If you are upgrading a node created using the manual installation described in Running a Full Node or Running an Archive Node, then you should change to the radixdlt directory. This is where radixnode will find your existing key file.

You may also need to set the current user as the owner of the radixdlt directory.

3. Install and Configure Docker

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

radixnode configure-docker

While it’s running, the program 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. This is order for your system to pick up the changes made by the script.

Exit ssh login and relogin back for user addition to group "docker" to take effect
To continue running the script successfully, you must log out of the session and log in again.

4. Set the Nginx password

The script has now installed the Docker instance, and will continue to install the Nginx web server which is used as a secure front end for your node. The next thing to do is set the administrator password for Nginx using the following command:

radixnode set-admin-password -m DOCKER

which will ask you to set a password for your Nginx admin user.

The script will then ask you to create an environment variable for your password. This variable can be stored in your user shell startup script (.bashrc):

 Setup NGINX_ADMIN_PASSWORD environment variable using below command . Replace the string 'nginx_password_of_your_choice' with your password

            echo 'export NGINX_ADMIN_PASSWORD="nginx_password_of_your_choice"' >> ~/.bashrc

Copy the entire echo command and replace nginx_password_of_your_choice with your own password before running the command.

If your startup script is something other than .bashrc then change the command to append the NGINX_ADMIN_PASSWORD to the correct file. For example, the zsh shell uses ~\.zshrc as its startup script, so use that instead:

echo 'export NGINX_ADMIN_PASSWORD="nginx_password_of_your_choice"' >> ~/.zshrc

Now reload your startup script, to include the new variable in your current session:

Remember to use the correct file name for your startup script.
source ~/.bashrc

5. Start up your Docker Node

Run the command below to install to set up your node.

radixnode setup-docker  \
     -n fullnode \      (1)
     -r 1.0-beta.35.1 \   (2)
     -u  \              (3)
     -t    (4)
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 this location
3 The -u option 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.
4 t is the IP address of a radix node that you can use to join the network. On executing the command, the script will download the configuration file from the specified node and attempt to make a connection. Select your closest node from the list below:
Europe US Australia Asia Region

The script will create a validator.ks key file and ask you for a password.

If you lose your key file then you will also lose your original node address when you generate a new key.

Always make sure that you create a copy of your key as soon as you’ve generated it.

6. Make sure the node is running

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

radixnode get-node-address

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

{"address": "brx1qsp2jfx4cnhl0vgd80q5qq0qk4wcz076pzgzdj3pefghp8vrxmxsnng02k4fu", "balance": {"balances": {}, "staked": []}}

7. Obtaining node information

The radixnode script allows you to interrogate your node for useful information, such as the external host IP and the software version. Just enter the following command:

radixnode system-info

8. Check the node is syncing

  1. Make sure you have the json processor installed:

    sudo apt install jq
  2. Execute the following command:

    curl -s -u admin:nginx_password_of_your_choice  -X GET -k 'https://localhost/system/info' | jq '.info .counters .ledger .state_version'
  3. Make a note of the number. Wait a few seconds, then run the same curl command again.

If the number changes between subsequent executions of the command then the node is syncing correctly.

If the number stays the same, the node is not syncing correctly. In this case, you can contact Radix engineers through the Discord Channel for help.

9. Stopping your Docker Node

This command will shut down a full node or an archive node, and is executed slightly differently depending on which type of node you’re running. The -f parameter is the name of the docker compose file used to build the service.

Stop a full node
radixnode stop-docker \
    -f radix-fullnode-compose.yml


Stop an archive node
radixnode stop-docker \
    -f radix-archivenode-compose.yml

10. Restarting your Docker Node

Restart the node using the following command:

radixnode start-docker \
        -f radix-fullnode-compose.yml \    (1)
        -t    (2)
1 The -f option is the name of the composition file to invoke the service. If your service is a full node then use radix-fullnode-compose.yml. Use radix-archivenode-compose.yml if you’re service is an archive node.
2 The -t setting is the trusted node IP address your service will use to attach to the Radix network. You can find a list of valid addresses here.
Use the same compose file and trusted node address for setting up the node, stopping it and restarting it.

More information on RadixNode Usage

You can use RadixNode to carry out more administration tasks. For example:

You can find more information about the RadixNode command set on the Node Runner Repository site.

If you have any questions or run into problems, then check our troubleshooting guide, or the FAQ page. You can also get help from the community and Radix engineers on the Discord channel.