Skip to content
A series of shell scripts used for configuring a Catapult node
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cat-config-linux added linux scripts Jul 4, 2019
cat-config-mac added linux scripts Jul 4, 2019
.gitignore changed seed folder loc Jun 28, 2019
README.md changed seed folder loc Jun 28, 2019

README.md

Catapult Shell Node Configuration Scripts

Table of Contents

Introduction

How-To

Concepts


Introduction

NOTE: These scripts are for configuring a Catapult node after it has already been compiled. Detailed instructions (perhaps some scripts!) for doing this will be coming soon.

These scripts were originally created by core developer Jaguar0625. I took them and added a few extra features to enhance the user experience, as well as some additional documentation so you can actually utilize these and understand what you're doing. These scripts:

  • Reset your Catapult node.
  • Configure your node for peer, api or dual mode (more detail below).
  • Configure your node with the necessary extensions for each respective mode.
  • Configure resources with a user-given keypair and necessary catapult-server paths.
  • Generate a nemesis block properties file with boot key and paths.
  • Generate mosaic ids for the given public key.
  • Generate a list of harvester keys and addresses, and configure the nemesis block file with them.
  • Generate the nemesis block, 64 byte hashes.dat, and a fresh data directory.

This is the setup that is required to get a Catapult node up and running. Luckily, these scripts do it in just a few steps. :)

How-To

Directory Structure

In order for these to work, a certain directory structure has to be adopted. This structure is similar to the catapult-service-bootstrap:

catapult-node-data/
├── data
├── nemesis
├── resources
├── scripts
├── seed
└──    

As you can probably guess, our node configuration scripts will end up being inside of the scripts/ directory.

Firstly, create a directory to house the above structure:

mkdir catapult-node-data && cd catapult-node-data
mkdir data
mkdir nemesis
mkdir resources
mkdir scripts
mkdir seed

Now, go ahead and move the cat-config found in this repo over to catapult-node-data/scripts

Running reset.sh

reset.sh will configure your node. Its usage is as follows, keep in mind the scripts utilize the zsh shell. Make sure you are in catapult-node-data/ when you run this:

zsh scripts/cat-config/reset.sh <node_type> <path_to_catapult-server_src> <private_key> <public_key>

Let's break this down:

  • node_type - This argument tells the script which kind of node to configure. There are three node types in catapult: dual, peer, and api. An explanation for each can be found in #concepts.

  • path_to_catapult-server_src - The FULL path to your catapult-server directory on your machine. catapult-server must be compiled and contain build/.

  • private_key and public_key - Your node's keypair. You can generate a keypair using a tool like the nem2-cli or at http://wallet.nemesis.land/#/developer-mode

Once you have your arguments in the correct order, you can simply run the script and watch it go! If all went well, you should see the nemesis block information at the bottom of the output. At any time if you want to change your node configuration, you may run reset.sh with different settings. Keep in mind that it will reset your chain!

Configure config-harvesting.properties

Before starting your node, take a private key from harvester_addresses.txt (it gets generated during reset.sh) and go into resources/config-harvesting.properties. Set the harvestKey to the private key you copied from harvester_addresses.txt.

Starting Catapult with start.sh

To start a Catapult service (server or broker), run this script from scripts/cat-config:

zsh scripts/cat-config/start.sh <server | broker> <path_to_catapult-server_src> --force

Let's break this down:

  • server | broker - This argument allows you to pass in the type of service you would like to start. server starts up your actual node, while broker will start Catapult's broker service.

    • Starting the server: zsh scripts/cat-config/start.sh server <path_to_catapult-server_src> --force

    • Starting the broker: zsh scripts/cat-config/start.sh broker <path_to_catapult-server_src> --force

  • --force - This argument deletes the .lock file that is usually generated in data/. You may, or may not, need to run this argument.

Concepts

Catapult Extensions

Extensions in Catapult are essentially modules that add features to the otherwise bare catapult-server. They range from extensions that are critical like consensus and networking to optional extensions like zmq messaging and other API conveniences.

Extensions are not meant to the confused with plugins. Extensions modify the core server, whereas plugins introduce new and different ways to alter the chain's state via transactions.

Catapult Node Types

These scripts introduce several interesting concepts about Catapult nodes. If you noticed, we are actually able to generate configurations for three types of nodes:

  • peer nodes are the "bare minimum" version of a Catapult node. It does not load API extensions like extension.filespooling or extension.partialtransaction, but rather it runs the backbone of the catapult-server architecture that handles consensus and networking. peer nodes require a few extensions in order to be operational.

  • api nodes introduce convenience APIs to interface with a given peer node. They load extensions like extension.filespooling to queue messages from the node to a broker, and extension.partialtransaction to enable the API node to identify and store partial aggregate bonded transactions.

  • dual nodes combine a peer node and api node into a single server instance. It loads extensions required for both peer and api nodes. If you chose this option in the script, you can see inside of your config-node.properties file that the node is set for both types.

You can’t perform that action at this time.