Launching a Cardano Node

The Cardano node is the core component that underpins the Cardano network. Ultimately, a blockchain network is just a collection of interconnected nodes, all working together to validate transactions and blocks by means of consensus. The consensus definition for any given network varies, but for the Cardano network, it's defined by the Ouroboros protocol.

Users participate in and contribute to the network by running a Cardano node. On a Testnet, nodes run on a network separate from the Cardano Mainnet to test and verify functionality in a safe sandbox environment.

We will launch a Cardano Node on the Preview Testnet and show how the same can be done on the Mainnet. Using the Testnet means that we can use Test ADA to send transactions rather than the real ADA.

Table of Content

Compile Cardano Node

Prerequisites

Before compiling the Cardano Node you need to make sure that you have set up the virtual machine for the node in the previous step.

Node Executable

Download the latest Linux release from  https://github.com/input-output-hk/cardano-node/releases

Look for "Downloads" section and pick a Linux Static Binary. Download the latest release and extract it from the archive.

wget https://update-cardano-mainnet.iohk.io/cardano-node-releases/cardano-node-1.35.7-linux.tar.gz
tar -xf cardano-node-1.35.7-linux.tar.gz

Copy the cardano-node and cardano-cli packages into the Linux bin folder so that it can be accessed from anywhere

sudo cp cardano-node /usr/local/bin/cardano-node
sudo cp cardano-cli /usr/local/bin/cardano-cli

Check that they are accessible.

cardano-node --version
cardano-cli --version

If the above command returns the node and cli versions, then you are ready to move to the next step. If it gives you an error, then check permissions and that the user can access the folder where you copied it.

Configuration

Create a folder for all files related to the cardano-node

mkdir cardano-node
cd cardano-node

Find the latest environment files for the Preview testnet here: https://book.world.dev.cardano.org/environments.html

wget https://book.world.dev.cardano.org/environments/preview/topology.json
wget https://book.world.dev.cardano.org/environments/preview/config.json
wget https://book.world.dev.cardano.org/environments/preview/byron-genesis.json
wget https://book.world.dev.cardano.org/environments/preview/shelley-genesis.json
wget https://book.world.dev.cardano.org/environments/preview/alonzo-genesis.json

The topology.json is already configured to support peer-to-peer (p2p) discovery of nodes to connect to, so you do not need to populate the topology file manually. This is a big improvement in 2023 for cardano-node

Create Launch Scripts

To run an instance of Cardano Node, create a bash script to configure options. Also, implement Cardano Node as a systemd service. Running Cardano Node as a systemd service maximizes the uptime of your stake pool by restarting the stake pool automatically if any stake pool processes may crash or when the computer reboots.

Make sure you are in the cardano-node folder

cd cardano-node

Using a text editor, create a file named startCardanoNode.sh and then add the following contents to the file. Check that the path /home/cardano/cardano-node is correct to where the config files were saved in the previous step.

#!/bin/bash
#
# Set variables to indicate Cardano Node options
#
# Set a variable to indicate the port where the Cardano Node listens
PORT=6000
# Set a variable to indicate the local IP address of the computer where Cardano Node runs
# 0.0.0.0 listens on all local IP addresses for the computer
HOSTADDR=0.0.0.0
# Set a variable to indicate the file path to your topology file
TOPOLOGY=/home/cardano/cardano-node/topology.json
# Set a variable to indicate the folder where Cardano Node stores blockchain data
DB_PATH=/home/cardano/cardano-node/db
# Set a variable to indicate the path to the Cardano Node socket for Inter-process communication (IPC)
SOCKET_PATH=/home/cardano/cardano-node/db/socket
# Set a variable to indicate the file path to your main Cardano Node configuration file
CONFIG=/home/cardano/cardano-node/config.json
#
# Run Cardano Node using the options that you set using variables
#
/usr/local/bin/cardano-node run --topology ${TOPOLOGY} --database-path ${DB_PATH} --socket-path ${SOCKET_PATH} --host-addr ${HOSTADDR} --port ${PORT} --config ${CONFIG}

Save the file. Set the right permissions:

chmod +x /home/cardano/cardano-node/startCardanoNode.sh

Create a DB folder

When you first launch cardano-node it can take up to 48 hours to sync with the blockchain. Because every node contains an entire history of the blockchain right from the beginning of time when the blockchain was first launched, it can take a long time to sync.

On the Mainnet it can take up to 48 hours. On the Preview Testnet, where the number of transactions since inception is much smaller, it should take a few hours to sync.

Create the db folder

mkdir /home/cardano/cardano-node/db

If you prefer to sync from the start then proceed to the next step. If you prefer to preload the db then load the content of the db folder from a shared drive, or USB stick.  

Create a Cardano Node Service

To run Cardano Node as a service, using a text editor create a file named cardano-node.service and then add the following contents to the file

# 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/startCardanoNode.sh'
KillSignal        = SIGINT
RestartKillSignal = SIGINT
TimeoutStopSec    = 300
LimitNOFILE       = 32768
Restart           = always
RestartSec        = 5
SyslogIdentifier  = cardano-node  
  
 [Install]
WantedBy          = multi-user.target

Save and close the cardano-node.service file. Move the cardano-node.service file to the folder /etc/systemd/system and set file permissions, type

sudo mv /home/cardano/cardano-node/cardano-node.service /etc/systemd/system/cardano-node.service
sudo chmod 644 /etc/systemd/system/cardano-node.service

To start Cardano Node as a service when the computer boots, type:

sudo systemctl daemon-reload
sudo systemctl enable cardano-node.service

This will ensure cardano-node starts in the background every time the server starts, or gets rebooted.

Managing the Cardano Node Service

To view the status of the Cardano Node service, type:

sudo systemctl status cardano-node

To restart the Cardano Node service, type:

sudo systemctl reload-or-restart cardano-node

To stop the Cardano Node service, type:

sudo systemctl stop cardano-node

To display and filter logs, type one of the following commands, for example:

journalctl --unit=cardano-node --follow
journalctl --unit=cardano-node --since=yesterday
journalctl --unit=cardano-node --since=today
journalctl --unit=cardano-node --since='2022-07-29 00:00:00' --until='2022-07-29 12:00:00'

Tips and Trick

A collection of useful code snippets to work with the cardano-node and cardano-cli

Use cardano-node from a remote machine

Setting up and running an instance of cardano-node requires a few hours of setup and a computer with enough memory. I strongly recommend everyone to go through the steps at least once to understand how it works and the architecture around it, but after that once you have a running node you should try and reuse it as much as possible - rather than setting up a new node every time you want to run some queries

You can download a precompiled version of the cardano-node and cardano-cli from github releases as explained in the previous step.  This will save you a few hours of not having to compile from the source

cardano-node on a remote machine

If you have a cardano-node instance running on a remote machine then you can expose the socket of the node to your home computer by creating an ssh tunnel like this:

ssh -L /tmp/node.socket:/home/cardano/cardano-node/db/socket cardano@server.public.ip.address

Then on your home machine set the global variable  CARDANO_NODE_SOCKET_PATH that the cardano-cli needs to communicate with the node:

export CARDANO_NODE_SOCKET_PATH=/tmp/node.socket

And then try running your cardano-cli executable on your home machine. This assumes that you are running on a Testnet, for which the --testnet-magic 2 is required

./cardano-cli query tip --testnet-magic 2

If your node is running on the Mainnet then replace --testnet-magic 2 with --mainnet

With this, you run any cardano-cli commands on your home machine while using the cardano-node from a remote server.

cardano-node in a docker container on a remote machine

You might have cardano-node instances that are running inside a docker container on a remote server. A common practice is for users running the cardano-node connected to the Mainneet on the remote server and then running another instance of cardano-node on the same server but inside a docker container.

If you are running an instance of cardano-node inside the docker container then you need to do an extra step to expose the socket from within the docker container to the remote server and then tunnel into the remote server from your home computer

First, you need to map the socket from the docker container to a local folder on the remote server. The example below is using the volumes section of the  docker-compose.yml file

...
volumes:
    - node-db-testnet:/data
    - /home/cardano/git/testnet/tsocket:/ipc
...

Then make sure to give it the right permissions, so that the user from the remote server can access the socket from the docker container  

sudo chmod 777 /home/cardano/git/testnet/tsocket/node.socket

And then from here, it is as if the socket was on the remote server, rather than in the docker, so you can ssh tunnel the socket back to your home machine like this:

ssh -L /tmp/node.socket:/home/cardano/git/testnet/tsocket/node.socket cardano@server.public.ip.address

Make cardano-cli launchable from any directory

When you download cardano-cli into a directory, you can launch it only from that directory. This is not convenient when you are working across directories and want to execute the command from the directory you are in.

You can create a symlink to your /usr/local/bin directory to solve this

sudo ln -s /<<path to cardano executables>>/cardano-cli /usr/local/bin/cardano-cli 

References

How to Set Up a Cardano Stake Pool - CoinCashew

Cardano Node Github repo

How Ouroboros Proof of stake works?

License

This work is distributed under a Creative Commons Attribution 4.0 International (CC BY 4.0) The license allows you to copy and redistribute the material in any medium or format, as well as remix, transform, and build upon the material for any purpose, including commercial, as long as you give appropriate credit to the creator.