Using Symbol Bootstrap

Quick Installation

On Linux systems using apt:

 sudo apt update
sudo apt install nodejs npm 
    docker docker-compose
node --version

If the obtained node version is high enough (see Requirements), then you can install Symbol Bootstrap:

 npm install -g 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 in any of the supported operating systems (Windows, Linux and Mac).

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

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

 

Requirements

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.
  • Port 7881 is used by the monitoring agent. Only required when enrolled to some of the Reward Programs, and can be customized.

Installation

Symbol Bootstrap is provided as an installable tool, there is no need to clone a repository and build it. Just run this from a terminal or command prompt:

 npm install -g symbol-bootstrap

Notes:

  • You can run the above command again to install a newer version of symbol-bootstrap every time one becomes available.

    Remember to stop symbol-bootstrap before upgrading and then start it again afterwards, as shown below.

  • If you get permission errors read nodejs’s guide to Resolving EACCES permissions errors when installing packages globally.

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
mainnet A single node that connects to the current public main network. Nemesis block is copied over. Requires an assembly, as shown below (configuration file).
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 test network. 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
mainnet peer The node is a harvester (configuration file).
mainnet api The node runs its own mongo database and rest gateway (configuration file).
mainnet dual The node is a harvester and runs its own mongo database and rest gateway (configuration file).
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).
bootstrap full It’s the default bootstrap preset plus 1 wallet, 1 explorer and 1 faucet. Great for demonstration purposes. 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), containing among other things the generated complete configuration file (target/preset.yml) ready to be used to build the network.

Note

On Linux, if you get the error Permission denied while trying to connect to the Docker daemon socket it means that your user does not belong to the docker group. Add it with:

 sudo addgroup $USER docker

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.

You then have to stop them with symbol-bootstrap stop.

 

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.

Did you find what you were looking for? Give us your feedback.