Introduction
This article explains the steps to set up a Dual Node for the Symbol blockchain. A Dual Node is a node that has two functions: a Peer Node that generates blocks (harvests) and an API Node that retrieves block information. By using symbol-bootstrap, you can easily set up and manage a Dual Node. Through this article, you will learn the basic setup steps and aim to smoothly operate a Symbol Dual Node.
Environment
We will use Ubuntu 24.04 as the OS and install the following:
Docker 27.5.1Volta 2.0.2Node.js 20.18.1
symbol-bootstrap 1.1.11
Installing Docker
Adding Docker’s apt repository
Add the GPG key.
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
Add the repository.
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Installation
Install Docker packages using the apt command.
Recent Docker versions can use compose without docker-compose, but since symbol-bootstrap uses docker-compose internally, install it as well.
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-compose
Add the user to the docker group to use Docker.
sudo usermod -aG docker <username>
Installing Volta + Node.js
Install from Volta, which allows easy version management of Node.js.
sudo curl https://get.volta.sh | bash
exec $SHELL -l
volta install node@20
Installing symbol-bootstrap
Although it is available on NPM, updates by the developer have stopped, so use the version maintained by Symbol core developers. Since there are no pre-built files, you cannot install it directly with npm install, so clone it locally first. The clone location is arbitrary.
git clone https://github.com/symbol/symbol-bootstrap.git
cd symbol-bootstrap
Install npm packages and build.
npm i
npm run build
Globally install symbol-bootstrap.
npm install -g .
Setting up a Dual (Peer+API) Node
Creating the node’s working directory
Create a directory to store node data. The location can be anywhere. In this article, we will create it in the /opt directory.
sudo mkdir /opt/symbol-node
sudo chown <username>: /opt/symbol-node
cd /opt/symbol-node
Creating a custom preset
vi custom-preset.yaml
Create custom-preset.yaml and input the custom preset.
# Maximum number of accepted delegates
maxUnlockedAccounts: 100
# Eviction rule when the number of delegates exceeds the limit
# Importance: By importance
# Age: By order of arrival
delegatePrioritizationPolicy: Age
# Address to receive harvest rewards
beneficiaryAddress: <address to receive rewards>
# Assembly
# peer, api, dual, demo, multinode, services
assembly: dual
# Preset
# bootstrap, testnet, mainnet
preset: mainnet
# Host settings
nodes:
- host: <hostname> # IP address or acquired domain
friendlyName: Friendly name # Node name (give an easy-to-understand name)
voting: false # Set to true if it will also be a Voting node (requires 3,000,000 XYM)
# HTTPS support (remove if not needed)
httpsProxies:
- excludeDockerService: false
# Maximum chain bytes per sync attempt
maxChainBytesPerSyncAttempt: 50MB
# Maximum bytes for block disruptor circular buffer
blockDisruptorMaxMemorySize: 1000MB
Generating node configuration and docker compose
symbol-bootstrap config -c custom-preset.yaml --upgrade
symbol-bootstrap compose --upgrade
If you change custom-preset.yaml, run symbol-bootstrap -c custom-preset.yaml --upgrade.
Opening ports
Open ports 7900, 3000, and 3001 for node communication and Rest gateway (HTTP/HTTPS).
sudo ufw allow 7900
sudo ufw allow 3000
sudo ufw allow 3001
Starting the node
Start
symbol-bootstrap run -d
Checking operation
symbol-bootstrap healthCheck
If it is running normally, you will see a message like this:
_ _ _ _ _
___ _ _ _ __ ___ | |__ ___ | | | |__ ___ ___ | |_ ___ | |_ _ __ __ _ _ __
/ __|| | | || '_ ` _ \ | '_ \ / _ \ | | _____ | '_ \ / _ \ / _ \ | __|/ __|| __|| '__|/ _` || '_ \
\__ \| |_| || | | | | || |_) || (_) || ||_____|| |_) || (_) || (_) || |_ \__ \| |_ | | | (_| || |_) |
|___/ \__, ||_| |_| |_||_.__/ \___/ |_| |_.__/ \___/ \___/ \__||___/ \__||_| \__,_|| .__/
|___/ |_|
2025-02-02T05:12:58.600Z info User for docker resolved: 1001:1001
2025-02-02T05:12:58.602Z info Running image using Exec: symbolplatform/symbol-server:gcc-1.0.3.7 openssl x509 -enddate -noout -in node.crt.pem -checkend 2592000
2025-02-02T05:12:59.096Z info The node.crt.pem certificate for node node will expire on Jan 31 12:32:28 2026 GMT. No need to renew it yet.
2025-02-02T05:12:59.138Z info Container db is running
2025-02-02T05:12:59.139Z info Container node is running
2025-02-02T05:12:59.149Z info Container broker is running
2025-02-02T05:12:59.149Z info Container rest-gateway is running
2025-02-02T05:12:59.152Z info Container node port 7950 -> 7950 is open
2025-02-02T05:12:59.153Z info Container rest-gateway port 3000 -> 3000 is open
2025-02-02T05:12:59.154Z info Testing http://localhost:3000/node/health
2025-02-02T05:12:59.239Z info Rest http://localhost:3000/node/health is up and running...
2025-02-02T05:12:59.239Z info Network is running!
Stopping the node
Stop the node during server or node maintenance.
symbol-bootstrap stop
Renewing certificates
The certificate used for node communication is valid for about one year. If it expires, the node will stop as it cannot communicate with other nodes. Remember to renew it. You can renew it one month before expiration. Use the --force option to force renewal.
symbol-bootstrap stop
symbol-bootstrap renewCertificates
symbol-bootstrap run -d
Troubleshooting
could not acquire instance lock "./data/recovery.lock"
If it did not shut down properly, the following files will remain in target/nodes/node/data.
- server.lock
- broker.lock
- recovery.lock
In this case, delete recovery.lock and start symbol-bootstrap again.
If successful, the recovery program will run and fix it.
rm target/nodes/node/data/recovery.lock
symbol-bootstrap run -d
If it still does not start, delete all .lock files and start symbol-bootstrap.
rm target/nodes/node/data/*.lock
symbol-bootstrap run -d
Conclusion
This completes the setup of a Dual Node for the Symbol blockchain. By referring to this article, you should be able to smoothly set up and manage your node. If you encounter any issues during node operation, use the official documentation and community to resolve them.
As a member of the Symbol network, let’s continue to contribute to the development of blockchain. If you have any questions, feel free to ask. Thank you for your hard work!