How to use this handy node deployment tool.
This guide explains the concepts behind Bitxor Bootstrap, a program that allows quickly configuring and running Bitxor nodes on multiple operating systems (Windows, Linux and Mac).
It can also deploy several nodes at once to quickly create a test network.
After reading this you will be able to better understand the Running a node and Private test networks guides.
This program replaces the previous tools bitxorcore-service-bootstrap and bitxor-testnet-bootstrap.
The setup scripts are automated using Docker. To run a node or test network, you will need to have installed the following tools:
Make sure that the client’s host is accessible from the internet and that the following ports are open and available:
Port 7900 is used by bitxorcore-client to communicate between nodes.
Port 3000 is used by the REST Gateway to expose the endpoints to interact with the node.
Port 3001 is used by the REST Gateway in HTTPS mode.
Bitxor 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 bitxor-bootstrap
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. Specify the preset with the ‑‑preset or ‑p parameters.
Preset |
Description |
|---|---|
|
A single node that connects to the current public main network. Genesis block is copied over. Requires an |
|
Autonomous network with 1 mongo database, 2 peers, 1 api and 1 rest gateway. Genesis block is generated (configuration file). This is the default preset. |
|
A single node that connects to the current public test network. Genesis block is copied over. Requires an |
Presets can be further customized by indicating an assembly (or flavor) which provides additional parameters. Specify the assembly with the ‑‑assembly or ‑a parameters.
Preset |
Available assemblies |
Description |
|---|---|---|
|
|
The node is a Peer node (configuration file). |
|
|
The node is an API node (configuration file). |
|
|
The node is both a Peer node and an API node (configuration file). |
|
|
The node is a Peer node (configuration file). |
|
|
The node runs is an API node (configuration file). |
|
|
The node is both a Peer node and an API node (configuration file). |
Furthermore, if additional configuration is required, a custom preset 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. All properties in the Network properties or Node properties guides can be set through this file, for example.
Specify a custom preset file with the ‑‑customPreset or ‑c parameters.
Note
If you ever change your custom preset file once your node is already running you will need to upgrade the node as explained in the Update nodes created with Bootstrap guide.
config commandBefore building the node or network a full configuration file has to be created by using the bitxor-bootstrap config command:
bitxor-bootstrap config -p <preset> -a <assembly> -c <custom_parameters_file.yml>
For example:
bitxor-bootstrap config -p bootstrap
bitxor-bootstrap config -p mainnet -a peer
bitxor-bootstrap config -p mainnet -a dual
bitxor-bootstrap config -p mainnet -a dual -c custom_parameters.yml
This will create a folder, called target by default (it can be changed with the ‑‑target or ‑t parameters), containing among other things the generated complete configuration file (target/preset.yml) ready to be used to build the node or 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
compose commandThis command prepares the necessary Docker files based on the provided configuration:
bitxor-bootstrap compose
Just like the config step, this only needs to be run once.
run commandFinally, execute this command to start the necessary Docker instances and boot your node or network:
bitxor-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 ‑‑detached or ‑d parameters.
You then have to stop them with bitxor-bootstrap stop.
start commandThe above three commands (config, compose and run) can be merged into one:
bitxor-bootstrap start -p <preset> -a <assembly> -c <custom_parameters_file.yml>
That’s right, a Bitxor node (or test network with many nodes) can be instantiated and booted with a single command!
Steps that only need to be done once (config and compose) will not be repeated, so you can use this command every time.
API nodes created using the api or dual assemblies accept HTTP commands through port 3000. HTTPS access can also be enabled, as described in the next two sections.
Note
The certificates used below will only be used for HTTPS communication with the REST API, not as node certificates for inter-node communication.
If you already have an SSL for your host you can pass it onto Bitxor Bootstrap inside a custom preset file.
In order for the custom preset file to be self-contained, though, your certificate’s Key and Crt files must be converted to a Base64 string and copied into the preset file:
cat restSsl.key | base64 -w 0
cat restSsl.crt | base64 -w 0
Copy the output of these commands into the preset file, in a section like this:
nodes:
- friendlyName: My Awesome Node # Use anything you want here
host: awesomenode.mycompany.net # Use your node's host name
gateways:
- restProtocol: HTTPS
openPort: 3001
restSSLCertificateBase64: >-
LS0tLS1CRUdJTiBDRVJUSUZ...Base64...==
restSSLKeyBase64: >-
LS0tLS1CRUdJTiBSU0EgUFJ...Base64...=
The provided certificate needs to be valid for the hostname awesomenode.mycompany.net. The domain needs to resolve the IP address of your node.
When the certificates eventually expire you need to update the custom preset file and then upgrade the node as explained in the Update nodes created with Bootstrap guide.
This option only leaves HTTPS port 3001 open, not HTTP 3000. Remember to open port 3001 in your firewall or security group. Port 3000 can be closed as it is not used anymore.
Bootstrap can also take care of obtaining the necessary SSL certificates through the public and free Let’s Encrypt service.
To enable it, just opt-in by adding an httpsProxies section to your custom preset file:
nodes:
- friendlyName: My Awesome Node # Use anything you want here
host: awesomenode.mycompany.net # Use your node's host name
httpsProxies:
- excludeDockerService: false
You need to own the domain awesomenode.mycompany.net and it needs to resolve the IP address of your node. The Let’s Encrypt service will handle the certificate creation and renewals for you.
Remember to open ports 3001 and 80 in your firewall or security group. Port 3000 may or may not be closed. Port 80 is needed by Let’s Encrypt.
Note
This option has been heavily inspired by this great blog. Bitxor Bootstrap simply bundles this solution, streamlining the process.
Read the complete list of bitxor-bootstrap commands.
Go ahead and create a node following the Running a node guide.
