Skip to content

Basics

Architecture⚓︎

The architecture for various components are already described at docs.cardano.org by CF/IOHK. We will not reinvent the wheel 😄

Manual Software Pre-Requirements⚓︎

While we do not intend to hand out step-by-step instructions, the tools are often misused as a shortcut to avoid ensuring base skillsets mentioned on home page. Some of the common gotchas that we often find SPOs to miss out on:

  • It is imperative that pools operate with highly accurate system time, in order to propogate blocks to network in a timely manner and avoid penalties to own (or at times other competing) blocks. Please refer to sample guidance here for details - the precise steps may depend on your OS.
  • Ensure your Firewall rules at Network as well as OS level are updated according to the usage of your system, you'd want to whitelist the rules that you really need to open to world (eg: You might need node, SSH, and potentially secured webserver/proxy ports to be open, depending on components you run).
  • Update your SSH Configuration to prevent password-based logon.
  • Ensure that you use offline workflow, you should never require to have your offline keys on online nodes. The tools provide you backup/restore functionality to only pass online keys to online nodes.

Pre-Requisites⚓︎

Reminder !!

You're expected to run the commands below from same session, using same working directories as indicated and using a non-root user with sudo access. You are expected to be familiar with this as part of pre-requisite skill sets for stake pool operators.

Set up OS packages, folder structure and fetch files from repo⚓︎

The pre-requisites for Linux systems are automated to be executed as a single script. To download the pre-requisites scripts, execute the below:

mkdir "$HOME/tmp";cd "$HOME/tmp"
# Install curl
# CentOS / RedHat - sudo dnf -y install curl
# Ubuntu / Debian - sudo apt -y install curl
curl -sS -o guild-deploy.sh https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/guild-deploy.sh
chmod 755 guild-deploy.sh

Please familiarise with the syntax of guild-deploy.sh before proceeding. The usage syntax can be checked using ./guild-deploy.sh -h , sample output below:

Usage: guild-deploy.sh [-n <mainnet|preprod|guild|preview>] [-p path] [-t <name>] [-b <branch>] [-u] [-s [p][b][l][m][f][d][c][o][w][x]]
Set up dependencies for building/using common tools across cardano ecosystem.
The script will always update dynamic content from existing scripts retaining existing user variables

-n    Connect to specified network instead of mainnet network (Default: connect to cardano mainnet network) eg: -n guild
-p    Parent folder path underneath which the top-level folder will be created (Default: /opt/cardano)
-t    Alternate name for top level folder - only alpha-numeric chars allowed (Default: cnode)
-b    Use alternate branch of scripts to download - only recommended for testing/development (Default: master)
-u    Skip update check for script itself
-s    Selective Install, only deploy specific components as below:
  p   Install common pre-requisite OS-level Dependencies for most tools on this repo (Default: skip)
  b   Install OS level dependencies for tools required while building cardano-node/cardano-db-sync components (Default: skip)
  l   Build and Install libsodium fork from IO repositories (Default: skip)
  m   Download latest (released) binaries for mithril-signer, mithril-client (Default: skip)
  f   Force overwrite entire content of scripts and config files (backups of existing ones will be created) (Default: skip)
  d   Download latest (released) binaries for bech32, cardano-address, cardano-node, cardano-cli, cardano-db-sync and cardano-submit-api binaries (Default: skip)
  c   Install/Upgrade CNCLI binary (Default: skip) # (1)!
  o   Install/Upgrade Ogmios Server binary (Default: skip)
  w   Install/Upgrade Cardano Hardware CLI (Default: skip)
  x   Install/Upgrade Cardano Signer binary (Default: skip)
  1. If you receive an error for glibc, it would likely be due to the build mismatch between pre-compiled binary and your OS, which is not uncommon. You may need to compile cncli manually on your OS as per instructions here - make sure to copy the output binary to "${HOME}/.local/bin" folder.

This script uses opt-in election of what you'd like the script to do (as against previous version that used to try and auto-detect versions). The defaults without any arguments will only update static part of script contents for you. A typical example install to install most components but not overwrite static part of existing files for preview network would be:

./guild-deploy.sh -b master -n preview -t cnode -s pdlcowx
. "${HOME}/.bashrc"

If instead of download, you'd want to build the components yourself, you could use:

./guild-deploy.sh -b master -n preview -t cnode -s pblcowx
. "${HOME}/.bashrc"

Lastly, if you'd want to update your scripts but not install any additional dependencies, you may simply run:

./guild-deploy.sh -b master -n preview -t cnode
Folder structure⚓︎

Running the script above will create the folder structure as per below, for your reference. You can replace the top level folder /opt/cardano/cnode by editing the value of CNODE_HOME in ~/.bashrc and $CNODE_HOME/files/env files:

/opt/cardano/cnode            # Top-Level Folder
├── ...
├── files                     # Config, genesis and topology files
│   ├── ...
│   ├── byron-genesis.json    # Byron Genesis file referenced in config.json
│   ├── shelley-genesis.json  # Genesis file referenced in config.json
│   ├── alonzo-genesis.json    # Alonzo Genesis file referenced in config.json
│   ├── config.json           # Config file used by cardano-node
│   └── topology.json         # Map of chain for cardano-node to boot from
├── db                        # DB Store for cardano-node
├── guild-db                  # DB Store for guild-specific tools and additions (eg: cncli, cardano-db-sync's schema)
├── logs                      # Logs for cardano-node
├── priv                      # Folder to store your keys (permission: 600)
├── scripts                   # Scripts to start and interact with cardano-node
└── sockets                   # Socket files created by cardano-node