Updated on Nov 16, 2021

Running a Full Cardano Node

As a developer the best starting point to Cardano is to get a good understanding of the Cardano node. This knowledge is essential whether you want to build DApps, wallets, integration tools, mint custom tokens or operate your own stake pool. As mentioned in the previous article, the full node is open for everyone to run and we strongly encourage every developer to learn how to do it.

We will break it down in five basic steps:

  1. Set up your Linux environment
  2. Clone and build cardano-node
  3. Configure the node
  4. Running and monitoring the node
  5. Interacting with the node using cardano-cli

Goals

After following the instructions in this post you will be able to run a full Cardano node, synchronise with the rest of the network and integrate with it via the cardano-cli and querying its internal metrics.

Prerequisites

A machine with at least 12GB RAM and 64GB free disk space.

Background

The Cardano node is a full node which contains the entire blockchain since its genesis and acts as the main point of contact from you as a client to the rest of the nodes in the network. Its main responsibilities are to:

Image courtesy of Cardano docs

When we build the cardano-node project it will produce two binary executables, cardano-node (server) and cardano-cli (CLI client).

Set up Your Linux Environment

At the time of writing, setting up your Cardano development environment in Ubuntu 20.04 is the easiest and most well-documented approach. There are a few ways to do so.

There are pros and cons to each of these options but the most important outcome is having a repeatable and reliable way of setting up your environment from scratch. This will give you confidence in spinning up a node as required across different networks and purposes.

Install Core Dependencies

There are several core dependencies to install via APT before you can build cardano-node.

sudo apt-get update -y
sudo apt-get upgrade -y
sudo apt-get install git jq wget curl bc make automake g++ build-essential pkg-config libffi-dev libgmp-dev libssl-dev libtinfo-dev libsystemd-dev zlib1g-dev libncursesw5 libncurses-dev libtinfo5 libtool autoconf htop net-tools chrony prometheus-node-exporter -y

Install Cabal, GHC and Libsodium

Once the core dependencies are installed we will move on to installing Cabal (the Haskell build orchestrator), GHC (the Haskell compiler) and Libsodium (the cryptography library).

# Cabal
mkdir -p ~/setup/cabal
cd ~/setup/cabal
wget https://downloads.haskell.org/cabal/cabal-install-3.4.0.0/cabal-install-3.4.0.0-x86_64-ubuntu-16.04.tar.xz
tar -xf cabal-install-3.4.0.0-x86_64-ubuntu-16.04.tar.xz
mkdir -p ~/.local/bin
cp cabal ~/.local/bin/
~/.local/bin/cabal update
~/.local/bin/cabal user-config update
sed -i 's/overwrite-policy:/overwrite-policy: always/g' ~/.cabal/config

# GHC
mkdir -p ~/setup/ghc
cd ~/setup/ghc
wget https://downloads.haskell.org/~ghc/8.10.4/ghc-8.10.4-x86_64-deb10-linux.tar.xz
tar -xf ghc-8.10.4-x86_64-deb10-linux.tar.xz
cd ghc-8.10.4
./configure
sudo make install

# Libsodium
mkdir -p ~/git
cd ~/git/
git clone https://github.com/input-output-hk/libsodium
cd libsodium
git checkout 66f017f1
./autogen.sh
./configure
make
sudo make install
export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"

Clone and build cardano-node

Now we can clone the cardano-node repository, retrieve the latest tagged version and build it. This process takes between 10-30 mins depending on your machine so feel free to grab some tea, coffee and/or snacks.

cd ~/git
git clone https://github.com/input-output-hk/cardano-node.git
cd cardano-node
git fetch --all --recurse-submodules --tags
git checkout $(curl -s https://api.github.com/repos/input-output-hk/cardano-node/releases/latest | jq -r .tag_name)
cabal configure --with-compiler=ghc-8.10.4
echo -e "package cardano-crypto-praos\n flags: -external-libsodium-vrf" >> cabal.project.local
~/.local/bin/cabal build all

📝 To update an existing node please verify prereqs in cardano-node Releases

Once that is completed, copy the built binaries to ~/.local/bin which will be part of the executable path.

cp -p "$(./scripts/bin-path.sh cardano-node)" ~/.local/bin/
cp -p "$(./scripts/bin-path.sh cardano-cli)" ~/.local/bin/

Post-build Scripts

For convenience it also makes sense to add amend the existing environment variables to be loaded automatically.

echo 'export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"' >> ~/.bashrc
echo 'export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.bashrc
echo 'export PATH="~/.cabal/bin:$PATH"' >> ~/.bashrc
echo 'export PATH="~/.local/bin:$PATH"' >> ~/.bashrc
echo 'export NODE_HOME="$HOME/testnet-node"' >> ~/.bashrc
echo 'export CARDANO_NODE_SOCKET_PATH="$HOME/testnet-node/socket/node.socket"' >> ~/.bashrc
source ~/.bashrc

echo 'export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"' >> ~/.bashrc
echo 'export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.bashrc
echo 'export PATH="~/.cabal/bin:$PATH"' >> ~/.bashrc
echo 'export PATH="~/.local/bin:$PATH"' >> ~/.bashrc
echo 'export NODE_HOME="$HOME/node"' >> ~/.bashrc
echo 'export CARDANO_NODE_SOCKET_PATH="$HOME/node/socket/node.socket"' >> ~/.bashrc
source ~/.bashrc

Shortcut #1: An Init Script

To save time from having to run these commands one-by-one, you can simply use our existing init.sh and run it all (i.e. install dependencies, clone+build, configure) with:

wget https://raw.githubusercontent.com/LovelaceAcademy/CardanoDevBox/main/init.sh
bash init.sh

📝 Note that it is configured (see Configure the Node below) for the testnet, but the mainnet versions of the commands are commented out. Comment/uncomment the testnet/mainnet versions to configure the desired environment

Shortcut #2: Download the Binaries

You can alternatively download the latest versions cardano-node and cardano-cli

After downloading you can simply extract the binaries and add them to your PATH. In the case of Ubuntu you can run

mkdir -p ~/.local/setup/cardano-node-1.34.1
cd ~/.local/setup/cardano-node-1.34.1
wget https://hydra.iohk.io/build/13066517/download/1/cardano-node-1.34.1-linux.tar.gz
tar -xf cardano-node-1.34.1-linux.tar.gz
rm cardano-node-1.30.1-linux.tar.gz
mkdir -p ~/.local/bin
cp cardano-cli cardano-node ~/.local/bin

📝 Note you will still need to run the Post-build Scripts for the desired environment above to add the binaries to your PATH and ensure cardano-cli communicates to the right Unix domain socket

Configure the Node

Your Cardano node needs to be configured correctly to connect to a Cardano network, and this is determined by four JSON configuration files. We will focus on the testnet first.

mkdir -p ~/testnet-node/config
mkdir -p ~/testnet-node/socket
cd ~/testnet-node/config
wget -O config.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/testnet-config.json
wget -O bgenesis.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/testnet-byron-genesis.json
wget -O sgenesis.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/testnet-shelley-genesis.json
wget -O agenesis.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/testnet-alonzo-genesis.json
wget -O topology.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/testnet-topology.json
sed -i 's/"TraceBlockFetchDecisions": false/"TraceBlockFetchDecisions": true/g' config.json
sed -i 's/testnet-shelley-genesis/sgenesis/g' config.json
sed -i 's/testnet-byron-genesis/bgenesis/g' config.json
sed -i 's/testnet-alonzo-genesis/agenesis/g' config.json

mkdir -p ~/node/config
mkdir -p ~/node/socket
cd ~/node/config
wget -O config.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/mainnet-config.json
wget -O bgenesis.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/mainnet-byron-genesis.json
wget -O sgenesis.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/mainnet-shelley-genesis.json
wget -O agenesis.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/mainnet-alonzo-genesis.json
wget -O topology.json https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/mainnet-topology.json
sed -i 's/"TraceBlockFetchDecisions": false/"TraceBlockFetchDecisions": true/g' config.json
sed -i 's/mainnet-shelley-genesis/sgenesis/g' config.json
sed -i 's/mainnet-byron-genesis/bgenesis/g' config.json
sed -i 's/mainnet-alonzo-genesis/agenesis/g' config.json

Running and Monitoring the Node

Now it just a matter of running your node pointing to the configuration files above.

cardano-node run \
    --topology ~/testnet-node/config/topology.json \
    --database-path ~/testnet-node/db/ \
    --socket-path ~/testnet-node/socket/node.socket \
    --host-addr 0.0.0.0 \
    --port 3001 \
    --config ~/testnet-node/config/config.json

cardano-node run \
    --topology ~/node/config/topology.json \
    --database-path ~/node/db/ \
    --socket-path ~/node/socket/node.socket \
    --host-addr 0.0.0.0 \
    --port 3001 \
    --config ~/node/config/config.json

If you are running the node for the first time it will need to fully synchronise with the blockchain. Verify that the running node process is exposing its internal metrics by running:

curl localhost:12798/metrics

Interacting with the Node using cardano-cli

The cardano-cli binary that is copied to the ~/.local/bin path is the main way to interact with your local Cardano node. You can run the following commands to familiarise yourself.

# Getting the current tip
cardano-cli query tip --testnet-magic 1097911063

# Export the protocol parameters to file protocol.json
cardano-cli query protocol-parameters --testnet-magic 1097911063 --out-file protocol.json 

# Getting the current tip
cardano-cli query tip --mainnet

# Export the protocol parameters to file protocol.json
cardano-cli query protocol-parameters --mainnet --out-file protocol.json

References

Create Cardano Keys and Addresses

Now that you have cardano-cli and a running cardano-node, continue to Keys and Addresses ➡️

CONTENTS