DEV Community: fboucquez

How to create a Symbol Testnet network

fboucquez — Fri, 04 Feb 2022 17:07:34 +0000

Introduction

There are several articles about how to create Symbol nodes connecting to Symbol Testnet or Mainnet networks. But, what if you want to create your own fully decentralized Symbol network for fun/testing?

If you want to test a Symbol network locally you can just use symbol-bootstrap. Run:

symbol-bootstrap start -p bootstrap -a multinode

This command will create a Symbol network bundled in a unique docker-compose. The compose runs 2 peers nodes, 1 API node, and a rest gateway.

This private network is great when testing new features, like a new transaction or new rest endpoint before the feature is deployed into a shared Testnet. Private local networks are also great for E2E testing, when you want to start a network in a given or "empty" state, run some operations, assert the new states and reset the network.

A local private network is not production-ready. Running multiple Symbol nodes in one machine is not recommended, it's not decentralized, other people cannot connect to the network easily.

In this guide, I'm going to explain how you can create your Symbol network, how you can create multiple 'seed' nodes, and how you can share the network configuration so other people can connect to it. The name of this Testnet is FerNet.

This guide uses a a new cli tool called symbol-network. The symbol-network cli scales symbol-bootstrap to create and manage multiple nodes, for new or existing networks.

Installation

Before starting, let's install the required tooling. The tolling required is the same as the standard symbol-bootstrap.

This guide assumes an Ubuntu distribution, other OSs would be similar.

1) Node, Docker, and Compose

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
apt-get update
apt-cache policy docker-ce
apt-get install -y unzip gcc g++ make nodejs unzip docker.io
docker --version

curl -L "https://github.com/docker/compose/releases/download/1.27.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
docker-compose --version

2) Install symbol-bootstrap

npm install -g symbol-bootstrap
symbol-bootstrap version
symbol-bootstrap verify

3) Install symbol-network

npm install -g symbol-network
symbol-network version
symbol-network verify

Network Layout

Before running symbol-network, it's good to think about the network layout we want initially for our network. My fernet network would be:

Based on Symbol Tesnet
Single currency, named, fernet.branca, same initial supply.
Network domain fernet.wtf. No hostname prefix.
Network Type Testnet
HTTP and HTTPS nodes
2 Voting Peers - 3M balance
1 Voting Dual - 3M balance
2 Harvesting Dual Nodes - 1M balance
Explorer and Faucet (services)
Some additional genesis block accounts for testing.

Network Configuration

Now that we know how the network should look, let's run the tool!

Init:

The first step is the init wizard:

mkdir symbol-fernet
symbol-network init --ready

The first questions are about the basic network configuration. These questions are the most common, advance tuning can be manually done later by changing the yml files this command creates.

This command asks for a 'master' password. The master password is used to encrypt the generated network and node keys.

The command skips this section if you are creating nodes for an existing network. For example, you want to create and maintain dozens of Testnet/Mainnet nodes.

The second part asks how many nodes you want to create for a new or existing network. We are going to fill in the numbers defined above.

Once the init command finishes, you can see that 3 files have been created:

network-input.yml: the not-expanded network layout. It defines how many of each node we want. If you pre-create this file, symbol-network init won't ask you any questions and just run.
key-store.yml: The file that contains the network keys, nodes keys, and voting files the tool generates. The private values are encrypted using the provided master password. You can decrypt the file using symbol-bootstrap decrypt --source key-store.yml --destination key-store-plain.yml command. Remember to remove key-store-plain.yml after use!
custom-network-preset.yml: The network preset your nodes would use when running. These files are like the -p mainnet and -p bootstrap for your network. This is NOT the custom preset of a given node. You can tweak it, for example, change the network supply or inflation.

The cli tool will recommend the different commands you can run next to continue the network creation process.

Expand nodes:

The second automatic step 'expands' the nodes so each node can be customized independently.

symbol-network expandNodes

This command creates the following file:

network.yml: It contains each node configuration, including their custom preset. It's possible to tune it by changing the default hostnames, friendly names or adding new custom preset properties like logLevel: Debug

Generate Nemesis:

The third automatic step is to 'generate' the nemesis block for your new network. The nemesis block includes all the seed nodes accounts, link transactions, faucet, and 'founder' accounts. The founder account is the account that keeps the remaining supply after the node and faucet account distribution. All these accounts can be found encrypted in the key-store.yml.

symbol-network generateNemesis

This command generates:

nemesis-seed: A folder containing the nemesis block of your network.
nemesis-target: A folder containing a temporary node used to generate the nemesis block. You can validate the generated network configuration in nemesis-target/nodes/node/server-config/resources and nemesis-target/reports files.

The nemesis-seed block along the custom-network-preset.yml could be shared so other people can connect to the network after launch.

Try the Nemesis Node:

Before creating the nodes to be published in your VPC infrastructure, you can try how everything looks by running:

symbol-bootstrap start -t nemesis-target --noPassword --detached --healthCheck --report --pullImages

Go to the local explorer at http://localhost:90.

Explorer shows the nemesis block, the seed accounts, the nodes' link transaction, etc.

Once you are happy, just stop the node:

symbol-bootstrap stop -t nemesis-target

Node generation:

Finally, to create the nodes' target folders and zip distributions ready to be deployed in your infrastructure.

symbol-network configureNodes --offline --zip

This command will ask for a new password, the 'node' password. The node password is used to encrypt each node individually. It's the password symbol-bootstrap asks when running the different commands. Use a different password than the master password.

This last command generates:

nodes: the generated configuration for each node.
distribution: the zip files of the nodes ready to be pushed to the VPC boxes.

Configuration backups:

It's recommended you version the different created files. I use git to commit and backup the files.

git init

My .gitignore file:

nemesis-target/databases/
nemesis-target/nodes/node/logs/
nemesis-target/nodes/node/data/
nemesis-target/gateways/rest-gateway/logs/
logs.log

Then commit all the other files for future reference. You may or may not want to backup in a remote github repository. Node and network private keys are encrypted in the key-store.yml file.

Network Deployment

The symbol-network doesn't handle the deployment. It is outside the current scope of the tool. The possible infrastructures, cloud providers, and options are limitless.

This is up to the developer to script it. You can use bash and scp, you can use Terraform and S3 buckets or Ansible scripts, etc.

The required process is fairly simple though:

Install symbol-bootstrap and its dependencies on each node VPC.
SCP or Pull the zip to each node VPC, unzip.
Update firewalls opening ports 80, 7900, 3000, 3001, 443 depending on the node type.
Update the DNS values linking nodes' hostnames with the VPC IPs.

The deployment process is similar to this guide although the zips for all the nodes are pre-created, you just need to deploy and symbol-bootstrap run -d them.

Network launch:

To run the network, connect to each box and run:

symbol-bootstrap run -d

YES! You have just launched a new full Symbol Network!

Node update:

The general process to upgrade a node is installing a new version of the symbol-bootstrap, and probably a custom-network-preset.yml (global change) or a custom-preset.yml (node change) upgrade. Then run:

symbol-bootstrap stop
symbol-bootstrap start -c custom-preset.yml --upgrade

Allow new nodes to connect:

If you want another person to connect to your network, share with him the custom-network-preset.yml and nemesis-seed folder. Then this person can run:

symbol-bootstrap start -p custom-network-preset.yml -a dual  -c my-new-node-custom-preset.yml

Note that official Symbol networks have the network preset and seed bundled on symbol-bootstrap. That's why you can just run -p testnet or -p mainnet. The process for the custom testnet network is the same, just that the network preset and nemesis seed are externally provided.

Contabo deployment

I deployed FerNet to contabo's VPCs. The nodes were located in:

dual-001.fernet.wtf
dual-002.fernet.wtf
dual-003.fernet.wtf
beacon-001.fernet.wtf
beacon-002.fernet.wtf
Faucet
Explorer

They have been shut down to save costs!

Contabo costs around 12 USD per node.
The cost is quite lower than Hetzner although Contabo's console is not nearly as nice.
You may need to upgrade storage or processing power depending on how much the network is used.

Conclusion

I've created Symbol Network from my experience creating the initial Mainnet and latest Testnets' nodes. It bundles the original private tooling in a user-friendly and open-source cli that uses and scales Symbol Bootstrap.
This new cli tool allows you to create and maintain new Symbol networks quickly as well as nodes for existing networks without losing the configurability.

Have a look! Feedback is always appreciated!

The 23 € Symbol Node

fboucquez — Tue, 13 Jul 2021 18:38:58 +0000

Introduction

Setting up a Symbol node is a great way to enter the NEM community. Your node will join 1000s of other nodes keeping the network healthy while you can earn some well-deserved XYM.

This guide will help to create your node in a cost-efficient and secure way. We will use symbol-bootstrap to set up the node and Hetzner cloud provider to run the virtual Ubuntu box. You can read more about nodes in the official documentation.

Prerequisites

In order to follow along with this tutorial, it would be best to have knowledge of Symbol Blockchain, Symbol Wallets, Linux, and Networking. You should try the guide on Symbol's TestNet and eventually create your MainNet node where real tokens are used!

You will need a private symbol account or Wallet with some XYM for the setup. We will call this account the funder account. In Testnet, you can get free XYM using the Testnet's faucet.

Creating the box using Hetzner

For this example, we are using Hetzner as it's user-friendly and fairly low-cost. You can use a similar approach with Digital Ocean or even AWS.

Log/Register into the Hetzner console
Create a new Project.
Click on Add a server and select the Location
For this example, select Ubuntu 20.4.
To reach the min CPU and Memory node requirements select the CPX41 type. This box currently costs ~22.90 euros per month.
The included 240GB volume is good enough for the current Symbol Testnet (2.6GB) and Mainnet (7.2GB). In the future, the volume would need to be expanded increasing the cost a little bit.
Create a firewall opening ports 3000 and 7900. Open also port 7881 if you are creating a Supernode. Port 22 is recommended to be opened only if you are connecting to the box's terminal. If you are not, remove 22 from the list.
Add the SSH key of your computer. This will allow you to connect to the box terminal.
Add a name and create the box
Once the server has booted, copy the public IP address.
If you have a domain name, now it's a good time to create a new hostname by linking the box's IP address.

Installing the required software in the Ubuntu box

Now we will install the required software to run a Symbol node using Bootstrap in the Cloud VM. The following setup is for a typical Ubuntu OS, other distributions may be slightly different.

Connect to the box's terminal using ssh:
```
ssh root@REPLACE_WITH_THE_BOX_IP
```

Install the following required software:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
apt-get update
apt-cache policy docker-ce
apt-get install -y docker-ce unzip gcc g++ make nodejs unzip docker-compose
docker --version
docker-compose --version

Install symbol-bootstrap tool:

npm install -g symbol-bootstrap@1.0.6-alpha-202105122247
symbol-bootstrap version

Create the bootstrap and docker user:

# Create the bootstrap user
adduser bootstrap
# Enter a password for the bootstrap user
usermod -aG sudo bootstrap
groupadd -f docker
usermod -aG docker bootstrap

Note: Version symbol-bootstrap@1.0.6-alpha-202105122247 is an alpha version with a new wizard feature we will be using.

Configuring the Symbol node

Here we have the option to create the Symbol node directly on the Cloud VM box, but for security reasons, we are going to create it a in separate private computer, aka, your own computer. Then, the configured node will be copied over to the VM box.

Install the required software in your private computer,

Install bootstrap and verify the installation

npm install -g symbol-bootstrap@1.0.8-alpha-202107131135
symbol-bootstrap version
symbol-bootstrap verify

Run the bootstrap wizard and follow the instructions. This is where the magic happens.
```
symbol-bootstrap wizard
```
Select the network, let's use Testnet for this guide.
Select your node assembly (Dual).
Enter a strong password. This password will be used to encrypt and decrypt the node's private keys. Keep this password and the bootstrap files safe!
Select your Symbol Reward Program if it applies to you.
Generate random keys. In this example, we are going to generate new random keys for our node. If you already have keys, you can enter their private part.
Enter the IP/Hostname of your node and a catchy friendly name.
Select the default security mode (PROMPT_MAIN_TRANSPORT) and enable voting if it applies to you.

Once the wizard finishes, it will create the custom-preset.yml file with your node's customization. This file includes the private keys of your node. The private keys are encrypted using the password provided in the wizard. Keep this file and the password safe!

The wizard displays the node's generated or entered accounts. The Main account is the account that "owns" the node. It defines the node's importance (or the chance to harvest a block) and links the different secondary accounts.

The custom preset will allow you to regenerate (most) of the node's configuration. The only exceptions are voting keys. If you regenerate your voting node, you will need to re-link the voting keys.

The wizard will also show different useful commands you can use to continue the node setup.

You now have the option to start the node or to create a zip of the node configuration that can be deployed to a different machine. In our case, we want the latter, create a zip to be deployed in the Hetzner VM:

symbol-bootstrap pack -p testnet -a dual -c custom-preset.yml

Bootstrap's pack, start, and config create the target folder. The target folder is the generated configuration based on the selected preset, assembly, and custom preset. Bootstrap maintains the files inside, they should not be manually changed. The way to tune them is via the custom preset file.

Configuring the node's accounts

A Symbol node requires several accounts and keys. Bootstrap handles them under the hood but you need to link them. Liking keys is a blockchain transaction that requires XYM to pay the nodes' fees.

First, you need to fund the node's main account. You can transfer a min amount of 10 XYM from your Symbol funder wallet providing the Main account's address.

Once your main account has enough XYM, you can link the node's keys using the following wizard.

symbol-bootstrap link --useKnownRestGateways -c custom-preset.yml --maxFee 100000

Your node is fully configured to run, now let's copy it to the Cloud VM box.

Running the node

Copy the zip file from your private computer into the Cloud VM and connect to it. Note that we are connecting and copying as the bootstrap Linux user, not as the root user.
```
scp testnet-dual-node.zip  bootstrap@REPLACE_WITH_THE_BOX_IP:~/target.zip
ssh bootstrap@REPLACE_WITH_THE_BOX_IP
```

Once in the box, unzip the target.zip file.

unzip target.zip -d symbol-node
cd symbol-node

Verify once again symbol-bootstrap installation.
```
symbol-bootstrap verify
```
Run the node!
```
symbol-bootstrap run -d
```

Once the node is running, you can check it by going to the next URLs from your browser:

These links display the node information and the (synching) chain state.

Upgrading your node

In general, to upgrade your node you need to connect to the VM box (remember to reopen port 22 in the firewall):

ssh bootstrap@REPLACE_WITH_THE_BOX_IP

Once in the terminal:

sudo npm install -g symbol-bootstrap
cd symbol-node
symbol-bootstrap stop
cp target backup-target -r
symbol-bootstrap start -c config-only-custom-preset.yml --upgrade -d

Before doing any update, it's recommended to backup the target folder (cp target backup-target -r). Once the network grows, the node's target folder could be fairly large. Backing up will require doubling the used disk space. A larger volume would need to be considered.

The --upgrade params recreates the node's configuration and docker-compose file upgrading any service. The target folder is upgraded, any manual changes done inside may be overwritten!

Node and account security

Why did we use a separate private computer to generate the configuration? Why not just run Bootstrap's wizard directly on the VM Cloud box? Some of the reasons:

Private keys are randomly generated or provided in the private machine, not in the Cloud VM box.
The main private key is never entered or stored in the VM box. The node certificates generation and the link transactions are performed from the private machine.
The node admin may want to use a fully disconnected offline machine to generate the keys, configurations, and link transactions.

If the Cloud VM box gets compromised, the hacker wouldn't be able to retrieve the main private key.

Other security recommendations:

If the node is not a voting node or it's not in the Symbol reward program, you can keep the node's main account with low funds. Your "wealthy" private or founder account could delegate to your node. When the founder harvests a block, it will receive the harvesting reward and the main account will receive the beneficiary account reward.
Wealthy accounts should be secured with a multisig account or with a hardware device like Ledger. Or both!
To reach the supernodes or voting requirements, the main account would need to be fully funded (with over 1m tokens). In this case, it's strongly recommended to convert the main account to multisig, ideally, using a hardware wallet as a cosigner.

You can read more about how to enable delegate harvesting and this awesome ultimate guide to start harvesting blocks post.

Should I run my own node?

In this guide, we explained how to run a node under 23 euros per month. But will the node pay for itself? Let's do some numbers.

At the very minute of writing, XYM price is 0.12 USD or 0.10 EUR. In XYM coins, the server costs around 230 XYM per month.

If any of the accounts delegating to your node harvests a block, your node's main account will receive 45 XYM. Meaning that your node needs to harvest around 5.1 blocks per month to pay for itself.

According to this super useful xym-calculator, to harvest those blocks your node needs to "collect" 133K XYM. Using Symbol's delegated harvesting, you don't need to have 133K XYM, instead, you need harvesters to delegate to your node this amount. Then, the node (probably) pays itself.

These numbers literally change every hour so if your margins are tight, you need to revisit them often.

The node will need to be supported. You need to spend some time keeping up with Symbol news and upgrades. If your node is down, neither the node nor the harvesters will harvest. You need to monitor the node to keep it running. Low to no downtime will keep your harvesters happy.

If running a node is not for you, you can always delegate your private wallet to another community node. Find one that brings you the best uptime and support!

Conclusion

I've created Symbol Bootstrap out of the necessity to create private networks quickly in order to end-to-end tests the Symbol's SDKs. From there, Bootstrap has evolved into a user-friendly way to create public Symbol nodes. This guide and Bootstrap's wizard reflect the learnings I have acquired along the way from NEM colleagues and the community.

Bootstrap lets you create all the types of nodes (Dual, API, Peer), include all the known components (Mongo, Server, Broker, Supernode Agent, Rest, Explorer, Wallet, Faucet, etc) for both public or private networks. It allows you to "save" your configuration with just a YML file and update your nodes with --upgrade. Bootstrap hides configuration and implementation details while retaining the tunability with custom presets.

If you are interested in creating a Symbol node from scratch without using Bootstrap, try this great Running a Symbol node manually guide. The Deploying node for paranoids post explains how to create the server certificates in detail.