Installing and Running a Node Using systemd
Introduction
You can install a Radix Node as a systemd service, without using Docker as a container. The example given here assumes the use of an AWS instance, but can be applied to any Unix-based system. There are a number of steps to the installation:
-
Create a
radixdlt
user for running the node. -
Install the required packages
-
Install and run the node.
-
Configure the Nginx server
If you’re looking to install the node as a Docker container, then follow the instructions here. |
Prerequisites
We’re assuming that you have access to a Debian-based (e.g. Ubuntu) server with 100 GB of free SSD space and network bandwidth of 10 GBps or above. Other variants of distributions and/or Unix versions could be configured in similar way. It’ll probably take about half an hour to run through the whole installation.
1. Install Required Packages
-
Execute the following command to make sure the packages on your system are up-to-date.
sudo apt update -y
-
You’re going to need to generate secure keys during the installation, so make sure that the necessary packages for this are installed.
sudo apt install rng-tools sudo rngd -r /dev/random
2. Configure the Ports
The node requires that a number of ports are accessible on your server. 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
If you are using a cloud service then you must also arrange for external port access through your service provider: this is usually done through the service management console. If you are hosting the service yourself, then you may need to open access to the ports through your hardware router. For more information on the ports used by the Radix service, please consult the Ports used by the Radix Node documentation. |
3. Create the Radix User
For security, you’re going to run the node as a specialized user, rather than an administrator.
-
Execute the following commands to create a new user called
radixdlt
.sudo useradd radixdlt -m
And then to set the password:
sudo passwd radixdlt
-
You’re going to allow the
radixdlt
user to manage theradixdlt-node
service by creating a file in/etc/sudoers
with the following content:sudo sh -c ' cat > /etc/sudoers.d/radixdlt << EOF radixdlt ALL= NOPASSWD: /bin/systemctl enable radixdlt-node.service radixdlt ALL= NOPASSWD: /bin/systemctl restart radixdlt-node.service radixdlt ALL= NOPASSWD: /bin/systemctl stop radixdlt-node.service radixdlt ALL= NOPASSWD: /bin/systemctl start radixdlt-node.service radixdlt ALL= NOPASSWD: /bin/systemctl reload radixdlt-node.service EOF'
-
You can check that the file has been created properly by executing the following command:
sudo ls -l /etc/sudoers.d
You should see the
radixdlt
file in the directory listing.
4. Create the system service file
Create a system service file for the node, and put it under the ownership of the radixdlt
user.
sudo touch /etc/systemd/system/radixdlt-node.service
sudo chown radixdlt:radixdlt /etc/systemd/system/radixdlt-node.service
5. Install the JDK Software Packages
-
Execute the following command to download the Java package:
sudo apt install -y openjdk-17-jdk
-
Install
unzip
to uncompress packed files, andwget
to download files from remote servers.sudo apt install -y unzip wget
6. Create Directories
Here, you will create directories which will eventually hold the Node software and the ledger data.
-
First, create the directory and set permissions for the Node software.
sudo mkdir /etc/radixdlt/ sudo chown radixdlt:radixdlt -R /etc/radixdlt
-
Now, create the directory and set permissions for the Radix ledger.
sudo mkdir /data sudo chown radixdlt:radixdlt /data
7. Download the Radix Distribution
Download and unpack the Radix distribution.
The following actions must be carried as the radixdlt user
|
-
Execute the following command to switch to the
radixdlt
user you created in Section 3, “Create the Radix User”.sudo su - radixdlt
-
Go to https://github.com/radixdlt/radixdlt/releases and look for the entry with the Latest release marker.
-
You should see a release asset
zip
file that starts withradixdlt-dist
. -
Paste the URL you copied into a
wget
command to retrieve thezip
file. -
Then unpack it.
unzip radixdlt-dist-1.1.1.zip (1)
1 The file name should correspond to the release version you have downloaded. Move the file to its executable directory.
mv radixdlt-1.1.1/ /etc/radixdlt/node
-
Change to the directory:
cd /etc/radixdlt/node
At this stage, it’s worth checking the directory by executing the ls -al
command. It should contain directories for bin
and lib
.
8. Create the Keys
You will use the Radix key generator to create secure keys for the node.
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. Always make sure that you securely back up your key file as soon as you’ve generated it, and carefully protect it. |
-
Create a directory to hold the keys.
mkdir /etc/radixdlt/node/secrets
-
Then, run they key generator
./bin/keygen --keystore=secrets/node-keystore.ks --password=node-password
This will create the keys and write them to the
secrets
folder.
Don’t forget to set your own password for the key! |
9. Create a file with environment variables
Now you’re going to create a file that will contain the environment variables for the service.
cat > /etc/radixdlt/node/secrets/environment << EOF
JAVA_OPTS="--enable-preview -server -Xms8g -Xmx8g -XX:MaxDirectMemorySize=2048m -XX:+HeapDumpOnOutOfMemoryError -XX:+UseCompressedOops -Djavax.net.ssl.trustStore=/etc/ssl/certs/java/cacerts -Djavax.net.ssl.trustStoreType=jks -Djava.security.egd=file:/dev/urandom -DLog4jContextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector"
RADIX_NODE_KEYSTORE_PASSWORD=node-password (1)
EOF
1 | This is the same password you used to generate the keys |
10. Configuration
In this part, you’re going to create all the configuration files for the node.
10.1. Create Node Configuration File
Create the file: /etc/radixdlt/node/default.config
and populate it with the following content:
ntp=false
ntp.pool=pool.ntp.org
network.id=1 (1)
node.key.path=/etc/radixdlt/node/secrets/node-keystore.ks (2)
network.p2p.listen_port=30001 (3)
network.p2p.broadcast_port=30000
network.p2p.seed_nodes=radix://rn1qgf0tug4nmxfa7su8zsu8pejzq48eeglvxf8le09cuy0nsghzg44weacz2q@3.109.36.249 (4)
network.host_ip=35.178.201.42 (5)
db.location=/data (6)
api.port=3334 (7)
api.transactions.enable=false (8)
api.sign.enable=true (9)
api.bind.address=0.0.0.0 (10)
network.p2p.use_proxy_protocol=false (11)
1 | The id of the Radix network. The value for Mainnet is 1 | ||
2 | the location and name of node key file.
|
||
3 | the TCP port for listening to inbound connections. Set the port address to 30001 so that it doesn’t clash with the Nginx server you’ll be installing later. | ||
4 | this is the address of the node you are connecting to. Select the node closest to your server from the following list: | ||
5 | the external ip address of your server. You can find out your external IP address with the following command:
|
||
6 | the location of the node’s ledger database. | ||
7 | the HTTP port for the node API. Set this port to 3334 to prevent clashes with the Nginx server. | ||
8 | set this to true if you want to enable the transaction stream.
|
||
9 | enable this so you can sign the transactions using the node wallet. How to sign the transaction is in section [sign-the-transaction]
|
||
10 | the address to use for the node API. | ||
11 | set this true if you using nginx or set it to false. This allows nginx to pass the remote ip address for tcp connections on gossip port. |
10.1.1. Changes in default.config settings for 1.1.0 compared to earlier releases
-
Settings that are not supported any more
-
api.archive.enable
, -
api.construction.enable
-
api.account.enable
-
api.validation.enable
-
api.archive.bind.address
-
api.archive.port
-
-
Settings that are removed and supported by /system endpoint and enabled by default
-
api.health.enable=true
setting is removed and /system/health provides same information as before -
api.version.enable=true
setting is removed and /system/version provides same information as before
-
-
Settings related to metrics
-
api.metrics.enable
is been removed and metrics is enabled by default. The/metrics
endpoint is moved/prometheus/metrics
endpoint
-
-
New settings in default.config
-
api.sign.enable
is new config that needs to be enabled so that one can sign transaction using node. -
network.p2p.use_proxy_protocol
is new config to enable nginx to foward IP addresses on tcp communications
-
-
Settings that have been renamed
-
api.node.bind.address
is renamed toapi.bind.address
-
api.node.port
is renamed toapi.port
-
10.2. Populate System Control File
The file /etc/systemd/system/radixdlt-node.service
configures the node to run a system service. You created the file in Section 4, “Create the system service file”, but now you’re going to populate it with the following:
[Unit]
Description=Radix DLT Validator
After=local-fs.target
After=network-online.target
After=nss-lookup.target
After=time-sync.target
After=systemd-journald-dev-log.socket
Wants=network-online.target
[Service]
EnvironmentFile=/etc/radixdlt/node/secrets/environment
User=radixdlt
WorkingDirectory=/etc/radixdlt/node
ExecStart=/etc/radixdlt/node/bin/radixdlt
SuccessExitStatus=143
TimeoutStopSec=10
Restart=on-failure
[Install]
WantedBy=multi-user.target
11. Start Your Node
You are now ready to start your node. Execute the command:
sudo systemctl start radixdlt-node.service
12. Enable Your Node at Startup
You can now enable your node service to start up at when the server starts. Execute the command:
sudo systemctl enable radixdlt-node.service
13. Installing Nginx
Nginx is the front-end web server that handles secure requests between the node and the outside world. The installation runs as a superuser, so if you are still using your terminal as radixdlt
user then exit the radixdlt
session now:
exit
Now run the following command to run the installation:
sudo apt install -y nginx apache2-utils
Nginx comes with a predefined site directories that you’re not going to need, so you can delete them.
sudo rm -rf /etc/nginx/{sites-available,sites-enabled}
14. Download Nginx Configuration Files
Download and unpack the Nginx distribution.
-
Go to https://github.com/radixdlt/radixdlt-nginx/releases and look for the entry with the Latest release marker.
-
You should see release assets for two .zip files.
If you’re running a full node then copy the URL for
radixdlt-nginx-fullnode-conf.zip
.Archive node is not supported from release 1.1.0 onwards
-
Paste the URL you copied into a
wget
command on your server to retrieve thezip
file. -
Unzip the nginx configuration you’ve just downloaded. Either:
-
Copy the files to the Nginx setup directory.
sudo cp -r conf.d/ /etc/nginx/
-
And now copy the nginx configuration files for your node type:
15. Create Nginx Cache Directory
Nginx requires a cache directory for storing the reusable artifacts it downloads. Use the following command to create the cache:
sudo mkdir -p /var/cache/nginx/radixdlt-hot
16. Create the SSL Certificates
You can use your own SSL certificates if you wish, but for convenience, you’ll find the instructions for creating a set here.
-
Create the directory to hold the certificates:
sudo mkdir /etc/nginx/secrets
-
Create the SSL keys using the following command:
sudo openssl req -nodes -new -x509 -nodes -subj '/CN=localhost' -keyout "/etc/nginx/secrets/server.key" -out "/etc/nginx/secrets/server.pem"
-
And now execute this command to make sure the keys are in the correct format:
sudo openssl dhparam -out /etc/nginx/secrets/dhparam.pem 4096
This command may take a minute or more to run. -
Run the next command to set the authentication password for the server’s admin user:
sudo htpasswd -c /etc/nginx/secrets/htpasswd.admin admin
-
You can set the authentication password for the server’s superadmin user:
sudo htpasswd -c /etc/nginx/secrets/htpasswd.superadmin superadmin
-
Similary you can set the authentication password for the server’s metrics user:
sudo htpasswd -c /etc/nginx/secrets/htpasswd.metrics metrics
17. Start Nginx
-
Now, to start Nginx, execute the following command:
sudo systemctl start nginx
-
And now run this command to make sure that
nginx
starts up when the host server restarts:sudo systemctl enable nginx
-
You can check if the service is running by executing this command:
curl -k -u superadmin:{nginx-superadmin-password} -X POST 'https://localhost/key/list' \ --header 'Content-Type: text/plain' \ --data-raw '{ "network_identifier": { "network": "mainnet" } }'
which spools out a few basic node details:
{ "public_keys": [ { "public_key": { "hex": "0291d7f4e9a28049385da46855dc5a25184d5759ff5518b6c0746ee81a98698035" }, "identifiers": { "account_entity_identifier": { "address": "rdx1qspfr4l5ax3gqjfctkjxs4wutgj3sn2ht8l42x9kcp6xa6q6np5cqdgy70cjj" }, "validator_entity_identifier": { "address": "rv1q2ga0a8f52qyjwza5359thz6y5vy646ela233dkqw3hwsx5cdxqr2qktp69" }, "p2p_node": { "peer_id": "rn1q2ga0a8f52qyjwza5359thz6y5vy646ela233dkqw3hwsx5cdxqr2c9p3km" } } } ] }
If you’re getting connection errors when trying to connect to the node, then you may need to restart both the node and
|
Your node doesn’t have any tokens attached to it when you first create it. You can send XRDs to it from your wallet, then execute the curl
command again to inspect the core api.
This is explained in detail on sections related to node registration steps
It might take some times for your tokens to appear, since your newly-created node will have to wait for the next epoch before it syncs with the rest of the network. If you want to know more about Radix epochs, then click here. |
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.
Where to next …?
Once your node is up and running you can configure it to run as a validator by following the steps in Registering a Validator Node