Using Symbol Bootstrap

This guide explains the concepts behind Symbol Bootstrap, a package which contains the necessary setup scripts to help developers quickly configure and run their own network or node.

After reading this you will be able to better understand the Creating private test networks and Running a test net node guides.

Note

This package replaces the previous tools Catapult Service Bootstrap and Symbol Testnet Bootstrap.

Requirements

Hardware

Symbol Bootstrap has been tested on computers with the following minimum requirements.

  • CPU: 2 cores.
  • Memory: 4GB.
  • HD: 20GB.

Note

In less powerful instances you might encounter issues installing or running the node.

Environment

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

Ports

Make sure that the server’s host is accessible from the internet and that the following ports are open and available:

  • Port 7900 is used by catapult-server to communicate between nodes.
  • Port 3000 is used by the REST Gateway to expose the endpoints to interact with the node.

Installation

Symbol Bootstrap is provided as an installable tool, there is no need to clone a repository and build it. Just do:

npm install -g symbol-bootstrap

Configuration

Presets

Node configuration is done through a YAML configuration file which specifies every possible network parameter. Since the complete file can be several hundred lines long, a number of presets are available to simplify its handling:

Preset Description
bootstrap Autonomous network with 1 mongo database, 2 peers, 1 api and 1 rest gateway. Nemesis block is generated (configuration file). This is the default preset.
testnet A single node that connects to the current public testnet. Nemesis block is copied over. Requires an assembly, as shown below (configuration file).

Presets can be further customized by specifying an assembly (or flavor) which provides additional parameters:

Preset Available assemblies Description
bootstrap light It’s a lighter version of bootstrap with 1 mongo database, 1 dual peer and 1 rest gateway. Great for faster light e2e automatic testing. Nemesis block is generated (configuration file).
testnet peer The node is a harvester (configuration file).
testnet api The node runs its own mongo database and rest gateway (configuration file).
testnet dual The node is a harvester and runs its own mongo database and rest gateway (configuration file).

Finally, if additional configuration is required, a custom YAML file can be provided. Any value in this file overrides the default values set by the preset or the assembly so it can be combined on top of them. Take a look at the Configuring network properties guide to know which parameters are available.

Creating the configuration file

Before building the network the full configuration file has to be created by using the symbol-bootstrap config command and providing the desired preset and assembly:

symbol-bootstrap config -p <preset> -a <assembly> -c <custom_parameters_file.yml>

Some examples:

symbol-bootstrap config -p bootstrap
symbol-bootstrap config -p testnet -a peer
symbol-bootstrap config -p testnet -a dual
symbol-bootstrap config -p testnet -a dual -c custom_parameters.yml

This will create a folder called target by default (It can be changed with the -t option). Inside there’s a folder called config containing, among other things, the generated complete configuration file (target/config/preset.yml) ready to be used to build the network.

Building the network and nodes

This command prepares the necessary Docker files based on the provided configuration:

symbol-bootstrap compose

It only needs to be run once.

Running the network

Finally, execute this command to start the necessary Docker instances and boot your network:

symbol-bootstrap run

Stop the process by pressing Ctrl+C.

Note

To run the docker containers in the background of your terminal, you can run the service in detached mode using the option --detach or -d.

The all-in-one start command

The above three commands (config, compose and run) can be merged into one:

symbol-bootstrap start -p <preset> -a <assembly>

That’s right, a test network or node can be instantiated and booted with a single command!

Next steps

Proceed to the following guides to put what you have learned into practice!

Read the complete list of symbol-bootstrap commands.