grzegorznowak.cardano_node

Cardano Node Role

This role installs a Cardano Node as a systemd service on Ubuntu and Debian operating systems. It uses Ansible to simplify and enhance the control of operations.

It can also add CNCLI if requested.

Supported Distributions

The addition of more supported distributions will depend on user feedback. Please share your use cases on the issue tracker.

Ubuntu Versions

20.04
18.04

Debian Version

bullseye

Installation

You can install it via:

ansible-galaxy install grzegorznowak.cardano_node
or by cloning the repository directly.

Example Playbook

There are two main installation methods:

Compiling from source
Using pre-built binaries from IOHK

You can choose the method with the cardano_install_method flag.

Using pre-built binaries is generally sufficient, but compiling from source allows for more customization.

This role can test both methods.

When Cloned from GitHub

- name: Set up Cardano Node
  hosts: all
  vars:
    cncli_add: true  # includes CNCLI
    cardano_wallets:  # creates two wallets
      - savings
      - operations
  roles:
    - cardano-node-role

When Installed with Ansible-Galaxy

- name: Set up Cardano Node
  hosts: all
  vars:
    cncli_add: true  # includes CNCLI
    cardano_wallets:  # creates two wallets
      - savings
      - operations
  roles:
    - grzegorznowak.cardano_node

Configuration & Usage

By default, Cardano installs for a user and group named cardano, which is recommended. You can find other settings in defaults/main.yml.

More examples and commands will be added in future updates.

NFT Tokens

This role can mint native NFT tokens efficiently. If a token is already minted in the desired amount, it won't try again.

Minted tokens will be sent to the address used for minting.

Basic configuration needed on the mainnet:

cardano_install_method: dist
active_network: main
cardano_wallets:
  - &wallet_default default
cardano_nfts:
  - slug: BurningGiraffe
    description: Burning Giraffe
    image: ""  # IPFS hash of the NFT
    name: Burning Giraffe
    id: 1
    open_period: 1000000  
    quantity: 10
    wallet: *wallet_default

Native Tokens

This role can also create native tokens (not NFTs) with the same idempotent minting process.

Basic configuration needed on the mainnet:

cardano_install_method: dist
active_network: main
cardano_wallets:
  - &wallet_default default
cardano_assets:
  - name: MyAsset
    quantity: 1000000
    wallet: *wallet_default

Payment Addresses

This role can manage ADA addresses.

NOTE: This role does not integrate with wallet software yet. It creates files necessary to send and receive payments using the command line. “Wallet” refers to a file path containing related files.

It only creates wallets that do not exist and reports any missing private keys. To keep things secure, it won't delete existing wallets.

# List of wallet names to track with the role
cardano_wallets:
  - savings
  - operations

Assuming default values are used, wallet addresses will be found at:

/home/cardano/wallets/savings/payment.addr
/home/cardano/wallets/operations/payment.addr

Along with the wallets' private keys.

Node Sync Status Assertion

To ensure the playbook does not proceed until the Cardano node is fully synced:

- name: Wait until fully synced
  assert_cardano_synced:
    cardano_node_socket: "{{ cardano_node_socket }}"
    cardano_bin_path: "{{ cardano_bin_path }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # for testnet only
  retries: 60
  delay: 240    # wait up to 4 hours for full sync
  become: true
  become_user: "{{ cardano_user }}"
  register: sync_check_result
  until: sync_check_result.progress | int == 100

Funds Assertion

To check that a specific address has enough Ada available:

- set_fact:
    wallet_to_check: default
    lovelace_needed: 1000000000

- name: Collect wallets
  cardano_wallet:
    cardano_bin_path: "{{ cardano_bin_path }}"
    name: "{{ wallet_to_check }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # for testnet only
  become: true
  become_user: "{{ cardano_user }}"
  register: wallet_results

- name: Ensure we have enough Lovelace
  assert_address_funded:
    cardano_node_socket: "{{ cardano_node_socket }}"
    cardano_bin_path: "{{ cardano_bin_path }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # for testnet only
    expected_lovelace: "{{ lovelace_needed }}"
    address: "{{ wallet_results['wallets_addresses'][wallet_to_check] }}"    
  retries: 60
  delay: 240    # wait up to 4 hours for full sync
  become: true
  become_user: "{{ cardano_user }}"
  register: lovelace_result
  until: lovelace_result.lovelace | int > lovelace_needed

General Settings

# Cardano user configuration
cardano_user: cardano
cardano_group: cardano
cardano_home_directory: "/home/{{ cardano_user }}"

# Installation option:
# src - compile from source
# dist - use official binary
cardano_install_method: dist

# Version details
ghc_version: 8.10.4
cabal_version: 3.4.0.0

# Only relevant for building from source
cardano_node_version: 1.33.0

# Only relevant for installing from binaries
cardano_hydra_build: 9941151
# Always confirm your sha value for security
cardano_dist_sha_256: eb7fbc652f79bcb8f56699ed7fee174a4ed321307c7086838d44972136795543
cardano_dist_url: "https://hydra.iohk.io/build/{{ cardano_hydra_build }}/download/1"

# Service Configuration
cardano_listen_addr: 127.0.0.1
cardano_listen_port: 22322  # Must be in the upper range for non-privileged users

# CNCLI configuration
cncli_add: false  # set to 'true' to enable CNCLI service

For more details, refer to the defaults/main.yml file.

Cardano CLI

One goal is to abstract Cardano operations with Ansible tasks, but you can also use the command line directly.

su cardano
cd ~/bin
./cardano-cli --help

For more usage details, visit the Cardano CLI documentation.

CNCLI

For details on using CNCLI, refer to the original repository.

Managing Services

You can manage the Cardano Node service like any other service:

# Check the Cardano Node status
systemctl status cardano-node
# Restart the Cardano Node
systemctl restart cardano-node
# View general logs
journalctl -u cardano-node

To manage the CNCLI sync service (when enabled):

# Check the CNCLI sync status
systemctl status cncli-sync
# Restart the CNCLI sync
systemctl restart cncli-sync
# View general logs
journalctl -u cncli-sync

Integration Testing

Locally on LXD

Ensure LXD is installed and configured.

Run the full test suite with ./test-local.sh.

Compiling required binaries can take a long time.

On Cloud via CI Pipeline

CI runs on Digital Ocean and triggers with every meaningful change in the main branch.

To keep costs down, building from source currently supports only the Focal Fossa distribution.

Pre-built binaries are tested on Focal and Bionic distributions.

Other supported platforms are being evaluated.

Motivation

This role explores the configuration of Cardano backend and services, with functionality expected to grow as we learn more.

Built with high Test-Driven Development (TDD) standards to ensure changes do not break existing components.

Always ask for tests when ordering your Ansible tasks.

When to Use This Role Over the Official Docker Image?

Docker is excellent for consistent images for specific tasks but presents challenges with networking and systemd. It may require adding layers of complexity for custom setups, which can be avoided by using this Ansible role.

If you’re not focused on a docker-first approach, you may prefer this role as it is more transparent and you know exactly what’s included.

Initial tests were conducted using LXD containers, which are lightweight and mimic actual servers more effectively than Docker.