Starting a relay node

Starting a node as a systemd service in relay mode

After downloading the cardano-node software from the Github Releases page (or building it from the source code, if you prefer: building instructions) and copying the cardano-node and cardano-cli binaries to /usr/local/bin, the next step is to create a dedicated user for running the cardano-node service, create the required folders and download the configuration files.

I am usually creating a user named "cardano", without any extra privileges (and without a password), for this purpose.

sudo useradd -m -s /bin/bash cardano

To login as this user, after connecting with ssh with an user with sudo rights, I am switching to cardano using the command:

sudo su - cardano

As the cardano user, I am creating the following folders:

mkdir ~/cardano-node ~/cardano-node/bin ~/cardano-node/config ~/cardano-node/db

The next step is to download the configuration files for the selected network (mainnet, preprod or preview) from here: https://book.world.dev.cardano.org/environments.html

This can be done like this for mainnet (and similar for preview or preprod, but downloading their similar config files):

cd ~/cardano-node/config
wget https://book.world.dev.cardano.org/environments/mainnet/config.json
wget https://book.world.dev.cardano.org/environments/mainnet/topology.json
wget https://book.world.dev.cardano.org/environments/mainnet/byron-genesis.json
wget https://book.world.dev.cardano.org/environments/mainnet/shelley-genesis.json
wget https://book.world.dev.cardano.org/environments/mainnet/alonzo-genesis.json
wget https://book.world.dev.cardano.org/environments/mainnet/conway-genesis.json

These files are all the configuration files required for running the cardano node.

After downloading them, the next step is to create a startup script inside the ~/cardano-node/bin folder:

cd ~/cardano-node/bin
cat >startNode.sh<<EOF
#!/bin/bash

DIRECTORY=/home/cardano/cardano-node
PORT=6000
HOSTADDR=0.0.0.0
TOPOLOGY=\${DIRECTORY}/config/topology.json
DB_PATH=\${DIRECTORY}/db
SOCKET_PATH=\${DIRECTORY}/db/node.socket
CONFIG=\${DIRECTORY}/config/config.json

cardano-node +RTS -N -RTS run \\
--topology \${TOPOLOGY} \\
--database-path \${DB_PATH} \\
--socket-path \${SOCKET_PATH} \\
--host-addr \${HOSTADDR} \\
--port \${PORT} \\
--config \${CONFIG}
EOF
chmod 755 startNode.sh

This will create the startNode.sh file with the content above starting with #!/bin/bash and ending before the EOF towards the end of the code, and chmod 755 startNode.sh will make the file executable.

Using this file, you can already start the node in relay mode, but you need to let it run inside the console. If you close the console, it will stop. The initial sync will take a long time (probably hours, because the ~/cardano-node/db folder has close to 100 GB that need to be downloaded. After the initial setup, the node needs to run permanently, to sync the new blocks.

The better way of starting the node is as a systemd service. For this, a systemd service needs to be defined, activated and started. As root (sudo -i as an user with sudo rights to become root), run the following commands:

cd /etc/systemd/system
cat >cardano-node.service<<EOF
# The Cardano node service (part of systemd)
# file: /etc/systemd/system/cardano-node.service 

[Unit]
Description      = Cardano node service
Wants            = network-online.target
After            = network-online.target 

[Service]
User             = cardano
Type             = simple
WorkingDirectory = /home/cardano/cardano-node
ExecStart        = /bin/bash -c '/home/cardano/cardano-node/bin/startNode.sh'
KillSignal       = SIGINT
TimeoutStopSec   = 300
LimitNOFILE      = 32768
Restart          = always
RestartSec       = 5

[Install]
WantedBy         = multi-user.target
EOF
systemctl daemon-reload
systemctl enable cardano-node.service
systemctl start cardano-node.service

This will create the cardano-node.service file, enable it (make it start automatically at boot) and start it.

To see and follow the logs, type the following command (as root):

journalctl -f -u cardano-node.service -n 50

If everything is fine, you should see the node syncing the blocks.

To see the progress of the sync, you can run the query tip command (as the cardano user):

cardano-cli query tip --mainnet

The response will be like this (with different numbers and block hash, and a percent lower than 100 while the node is still not in sync):

{
    "block": 9470184,
    "epoch": 444,
    "era": "Babbage",
    "hash": "25add230783281b0be4337dbf36bafe18897bf451eb211cbe5977ca14f61c92f",
    "slot": 106842959,
    "slotInEpoch": 398159,
    "slotsToEpochEnd": 33841,
    "syncProgress": "100.00"
}

If this command is not running, then you need to set the CARDANO_NODE_SOCKET_PATH environment variable, pointing to the node socket (defined in the startNode.sh file above):

export CARDANO_NODE_SOCKET_PATH=/home/cardano/cardano-node/db/node.socket

To make it set automatically at the login, put it in the .bashrc file (in the cardano user's home):

echo "export CARDANO_NODE_SOCKET_PATH=/home/cardano/cardano-node/db/node.socket" >>~/.bashrc

In case you did not do it already, also set the LD_LIBRARY_PATH environment variable in the ~/.bashrc` file:

echo 'export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"' >>~/.bashrc

In case the cardano-node or/and cardano-cli files are not found, make sure you copy them to /usr/local/bin or another folder which is in your $PATH environment variable. I prefer having them in usr/local/bin.