Running a test net node

This guide will walk you through the process of setting up your node to join Catapult’s public test network.

The test network mirrors the same technology and features of the future main public network. You can use the test net to experiment with the offered Catapult’s transaction set in a live network without the loss of valuable assets.

Note

The network might be offline or replaced without notice because it is used extensively for testing purposes. To work in a private environment network, install a local network for learning and development purposes.

Hardware requirements

Catapult nodes have been tested on computers with the following minimum requirements.

  • CPU: 2 cores or more
  • Memory: 4GB or more
  • HD: 20GB or more
  • OS: Linux or Mac

Although you might be able to run the software in less powerful instances, you might encounter some issues while installing or running the node.

Environment requirements

The setup scripts are automated using docker. To run a test net node, you will need to have installed the following docker tools:

Note

The release images target modern x86 architectures. It has been reported that errors are experienced on some older machines provided. If you run into any related issues, please report in the slack group (#help).

Installation

Note

These instructions are for the newer Catapult test network deployments (ie: will use symbol.xym as the network currency mosaic). If you have previously been running a node on the older test networks using nem.xem (pre 0.9.2.1), you will be redeploying your node and syncing with a different network. Any account(s) you might have been using on the old network will have no balance if moving to a new network.

The package symbol-testnet-bootstrap contains both assemblies ready to be installed.

  1. Download the latest release of the package, or clone the repository directly using Git.
git clone https://github.com/nemfoundation/symbol-testnet-bootstrap.git
  1. Choose the assembly distribution you want to install.

In short, if you want to be able to interact with your node, you need to run the API assembly. On the other hand, if you want a node dedicated exclusively confirm transactions, deploy the Peer assembly.

cd symbol-testnet-bootstrap/api-harvest-assembly

or…

cd symbol-testnet-bootstrap/peer-assembly
  1. Run the node with docker-compose.
sudo docker-compose up --build --detach

You should see docker downloading the container images for the first time. Then it should run the setup and finally startup the service.

To stop all the running services, run sudo docker-compose down in the same directory you executed the up command.

Peer assembly

The Peer assembly will set up a Peer only node.

API harvest assembly

The API harvest assembly will set up a dual-purpose API and Peer node, as well as the Rest gateway that transactions can be submitted to and data read from.

You can verify that the node is running by opening a new browser tab with the following URL: localhost:3000/chain/height.

Note

The software should expose the port 3000 by default. If you cannot access the REST Gateway from outside, it might mean that the port is closed by default by your machine or hosting provider so you will have to open it in order to access from outside the machine.

Note

API nodes take up more memory and storage than Peer nodes. If you have memory or storage constraints and you are running into issues, it is recommended you switch to running a Peer only node instead.

Configuring node properties

After running the node for the first time, you can change a set of properties such as the node’s public key or the harvesting configuration.

A file config-input.yaml will be generated with the default values. Depending on the assembly chosen, this file will be located under the peer-assembly/peer-node/ or api-harvest-assembly/api-node.

  1. If the node service is running, run sudo docker-compose down under the same directory you executed the up command.
  2. Edit the properties file config-input.yaml with a text editor.
  3. Save the changes and apply them with the command sudo docker-compose up --build --detach.

Interacting with the test network

To interact with your node, create first an account and acquire test symbol.xym.

Then, read and write data from the network with the following tools:

On this portal you can find information about Catapult’s features and self-paced guides on how to use the software development kits.