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 learning how to do it.
We will break it down in five basic steps:
- Set up your Linux environment
- Clone and build cardano-node
- Configure the node
- Running and monitoring the node
- Interacting with the node using cardano-cli
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:
- Uphold the Ouroboros consensus algorithm
- Maintain the ledger and accounting model
- Expose integration endpoints for clients and nodes
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.
- Run Ubuntu as the default OS or dual boot it on your device
- Run Ubuntu as a local VM (Windows, macOS)
- Run Ubuntu on a cloud VM and SSH (Windows, macOS, Linux)
- Run Ubuntu using WSL2 (Windows)
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-188.8.131.52/cabal-install-184.108.40.206-x86_64-ubuntu-16.04.tar.xz tar -xf cabal-install-220.127.116.11-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 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/
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
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
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 the mainnet versions of the commands are commented out. Comment out the corresponding testnet commands and uncomment the mainnet versions to run a mainnet node
Shortcut #2: Download the Binaries
You can alternatively download the latest versions
📝 Note you still need to configure the node for the mainnest or testnet environments
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
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 | grep -i epoch
Interacting with the Node using cardano-cli
cardano-cli binary that is copied to the
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
Understand Cardano Primitives: Keys and Addresses
Continue to Keys and Addresses ➡️