Running a Full Node

Introduction

A Full Node simply connects to the network, synchronizes ledger state, and observes the status of the network. It can be thought of as a kind of “wallet” that is connected directly to the network, with the Node’s own account available for programmatic control.

Reasons to run a full node include:

  • Prerequisite to running the node as a validator node

  • Observing the network state and operation directly and trustlessly

  • Operating a trustless account using programmatic controls. (The current Radix Desktop Wallet cannot be used as a GUI for a full node’s internal account)

Once running, a full node offers two interface paths on a private port:

The /node endpoint can be used to conduct transactions from the node’s account, including validator registration. The node’s account must hold XRD tokens to pay for network fees on these transactions.

The /system endpoint can be used to query aspects of the node and network such as current version, current peers, etc.

Full documentation of endpoints under /node and /system paths will be available at mainnet launch.

This guide will run you through an example installation and deployment of a Full Node.

Installing a Full Node as a Docker Instance in the Cloud

We’ve split the installation into discrete stages:

  • Installing Docker and the secure key generation tools.

  • Using the keygen application to generate secure keys for your service.

  • Installing and running the node on a provisioned server instance.

  • (An optional step converts the node into a validator, which is covered here)

We’re using Amazon Web Services throughout our example, but you can install Radix nodes on any cloud service that supports Java, such as Google’s cloud platform or Microsoft Azure – or follow similar step to deploy on a private server.

Prerequisites

We’re assuming that you’re comfortable provisioning a cloud service instance and installing/running Docker on it. You’ll also need a working knowledge of Git, and the UNIX command line.

AWS provisioning is beyond the scope of this exercise, but there are plenty of resources dotted around the web which will help you to get started. You will also need a working knowledge of Docker.

The provisioned AWS service

We recommend the following hardware specification as a minimum starting point.

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

c5.xlarge

4

8

Provision a gp2 storage volume.

You should initially provision 100 GB of SSD space

Up to 10

Ubuntu 20.04.2.0 LTS (Focal Fossa)

If you’re using a service provider other than Amazon, then aim for a similar spec.

Docker Installation

If you’re using the provision recommended in the section above then you can log into the instance and run the following commands to install docker and docker-compose.

  1. Create the directory for the compose scripts:

    sudo apt update
    mkdir radixdlt
    cd  radixdlt
    All further instructions assume you are running commands from directory radixdlt
  2. Install wget, Docker and the tools for key generating randomized keys:

    sudo apt install wget
    sudo apt install docker.io
    sudo apt install docker-compose
    sudo apt install rng-tools
    sudo rngd -r /dev/random
  3. Add user to Docker group:

    sudo groupadd docker
    sudo usermod -aG docker $USER
    newgrp docker

Get the Docker Compose Script

The distribution files contain the Docker compose scripts needed to build the service.

  1. Go to https://github.com/radixdlt/radixdlt/releases and look for the entry with the Latest release marker.

  2. You should see release assets for two .yml files. Copy the URL for the radix-fullnode-compose.yml file.

  3. Paste the URL you copied into a wget command on your server to retrieve the yml file.

Generate the keys

You’ll need the Radix Key Generator application to create secure keys for the node once it’s installed. (It’s a good idea to generate the keys first, just to get them out of the way).

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

As a validator, this means your delegators will have to unstake you, then restake under your new address.

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

You can check for the latest version of the keygen program here:

which should be used in the command given below to generate the secure keys.

docker run --rm -v ${PWD}:/keygen/key radixdlt/keygen:1.0-beta.33 --keystore=/keygen/key/validator.ks --password=passw0rdOfYourCho1ce

If you check the directory, you should now have a key file called validator.ks.

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.

You must change the key file’s permissions so that container can use it.

sudo chmod 644 validator.ks

Setting up your Environment

The installation uses a Docker compose script to build the instance.

Create the environment variables

The compose script needs two pieces of information from you before it can run:

RADIXDLT_NODE_KEY_PASSWORD

The password you used when creating the secure keys.

RADIXDLT_NETWORK_NODE

This is the IP address of the node on radix network that your own node will use to join the network. Radix has a number of nodes set up world-wide. Use the address closest to your server’s location:

Europe US Australia Asia Region

52.48.95.182

3.229.229.42

13.237.131.119

65.0.140.17

54.220.72.167

54.162.38.223

52.62.252.194

65.1.199.241

54.228.40.6

54.162.91.167

52.62.40.95

65.1.232.232

63.35.3.57

54.82.244.245

52.64.238.70

65.2.154.228

Set up the address and the password by creating environment variables on the instance:

export RADIXDLT_NETWORK_NODE=52.48.95.182
export RADIXDLT_NODE_KEY_PASSWORD=passw0rdOfYourCho1ce

Configure the Ports

The node requires that a number of ports are accessible on your server instance. Ensure that ports 443 and 30000 are available and can be seen externally.

HTTPS port for all API end points
 sudo ufw allow 443/tcp
GOSSIP port for node to node communication
 sudo ufw allow 30000/tcp

Bear in mind that you must arrange for port access outside your cloud server instance: this is usually done through the management console provided by your cloud service.

For more information on the ports used by the Radix service, please consult the Ports used by the Radix Node documentation.

Retrieve the configuration data for the node

This is not as painful as it sounds; all you need to do is grab the universe.json file from the node you’re connecting to. This is the address you defined in the compose script:

You can use curl to retrieve the file from the node address.

curl -k https://52.48.95.182/universe.json > ./universe.json

At this point in directory radixdlt, you should have three files:

  • radix-fullnode-compose.yml

  • validator.ks

  • universe.json

Configure Nginx Admin password

The node uses Nginx as its front end server. During startup, it creates an HTTP basic auth user named admin. The password is generated automatically and printed to the logs. If you want to use your own password, you will need to use the Docker instruction below to set the password before running the node installation.

docker run --rm -v radixdlt_nginx_secrets:/secrets radixdlt/htpasswd:v1.0.0
htpasswd -bc /secrets/htpasswd.admin admin <<nginx_password_of_your_choice>>

If you omit the command, then nginx will create a password and print it out in the log. It will not appear in the logs if the nginx container restarts for any other reason.

Running the node

Run the compose script to install and run the node.

docker-compose -f radix-fullnode-compose.yml up -d

At this point, your node is running in full mode, so if you don’t have a requirement to run as a validator then you can quite happily stop here. You may now connect to your node via the JSON-RPC API to make queries against the current network state, or to create and submit transactions. See The Radix Node API for more. If you want validator functionality, then press on …

Troubleshooting

If your node isn’t running at this point, then consult the Troubleshooting Guide, or drop a message on Discord where Radix staff and community will be happy to help out.