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.
The setup scripts are automated using docker. To run a test net or node, you will need to have installed the following tools:
Make sure that the server’s host is accessible from the internet and that the following ports are open and available:
7900
is used by catapult-server to communicate between nodes.3000
is used by the REST Gateway to expose the endpoints to interact with the node.7881
is used by the monitoring agent. Only required when enrolled to some of the Reward Programs, and can be customized.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.
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.
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
This command prepares the necessary Docker files based on the provided configuration:
symbol-bootstrap compose
It only needs to be run once.
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
.
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!
Proceed to the following guides to put what you have learned into practice!
Read the complete list of symbol-bootstrap
commands.