Node Setup

Note

This information can be used by STRATO node administrators.

Overview of Node Setup

This section provides the final steps to deploy a STRATO network. Prior to setting up any nodes, STRATO Vault must be set up (See STRATO Vault deployment instructions).

Each STRATO network consists of multiple STRATO nodes connected over peer-to-peer (P2P) protocol accompanied by at least one separate STRATO vault for user key storage storage to which nodes connect.

One STRATO node is deployed as a set of Docker containers using the docker-compose.yml template. The following is support to deploy nodes connecting to the existing BlockApps' STRATO Mercata network.

Consensus

To get information about the consensus algorithm used in STRATO networks, see PBFT Consensus section.

License

Deploying a STRATO node requires a BlockApps STRATO license and the individual credentials provided by BlockApps to access BlockApps' Docker Registry. Please reach out to sales@blockapps.net.

Prerequisites

Make sure the following prerequisites are met for each of the STRATO nodes being deployed:

1. A STRATO license is acquired
2. The hardware and software requirements are satisfied (see System requirements)
3. OAuth2.0 credentials are obtained (see Identity Provider Configuration)
4. TLS/SSL certificate obtained for your DNS address (see Obtaining TLS certificate)
5. (Removed in STRATO v7.5) (Optional, for enabling the External Storage feature) External Storage credentials are obtained (see External Storage)
6. STRATO Vault is deployed with a valid url to connect to (See STRATO Vault Deployment)

Deployment Tool

STRATO containers are deployed using the docker-compose.yml template file and the Docker Compose tool. The template file contains environment variables and configuration placeholders that need to be populated ("configuration options"). The STRATO Getting Started tool should be used to streamline the configuration process.

Download:

git clone https://github.com/blockapps/strato-getting-started
cd strato-getting-started
sudo ./strato --help

STRATO Getting Started tool:

• Automates the process of downloading the docker-compose.yml template file and pulling the Docker images.
• Collects environment variables provided at boot time (see the ./strato --help output for the list) and populates the template placeholders accordingly.

Most used commands:

• ./strato --compose - downloads the docker-compose.yml template file of latest STRATO release version
• ./strato --pull - pulls Docker images listed in docker-compose.yml file from BlockApps' Docker Registry (requires login)
• <config options> ./strato --blockstanbul - deploys a STRATO node with the configuration options provided
• ./strato --wipe - clears the STRATO node containers and all data volumes (does not apply to Docker images)
• ./strato --drop-chains - clears the STRATO node containers and data volumes except Vault data (stored in Postgres DB container's docker volume). Vault data stores the encrypted user keys providing the access to blockchain accounts (see User Identity - Key Vault)
• ./strato --get-address - get the address of the STRATO node (see PBFT Consensus for use cases)
• ./strato --get-pubkey - get the public key of the STRATO node (see Privacy for use cases)
• ./strato --set-password (Removed in STRATO v9.0) - manually re-enter the Vault password after Vault container restart. PASSWORD=my_password environment variable is optional for the command and is not recommended to use in production environments

Run

With multiple configuration options provided, the run commands to deploy STRATO can become complex. It is a good practice to keep them in shell script files (.sh) to maintain the configuration overtime and to have a reference of what configuration is currently running on your host.

From a network structure standpoint there are two types of STRATO nodes:

• Root node - the first node in the network that instantiates the blockchain data and is assigned the initial PBFT validator and admin node
• Secondary node - the node joining the existing network by connecting to one of its nodes and fetching the blockchain data from the network ("syncing")

The run commands will differ in a list of required configuration options for root and secondary nodes.

Configuration Options

While some configuration options have a narrow use, others are used commonly with most node deployments. Following is the list of commonly used options:

• NODE_HOST- hostname/IP and a port of the node being deployed (e.g. example.com:8080 or 203.0.113.1:8080, default: localhost:80)
• BOOT_NODE_IP - IP of another node in a network
  • Used to obtain network information from another node at boot time
  • Should also be provided on the root node to enable re-sync in cases like node upgrade
  • For a root node's initial deployment, this can be either skipped or set with the IP of one of the future nodes of the network
• isRootNode - (true/false) Whether this node is a root node
• HTTPS_PORT - port for HTTPS traffic listener
  • Only used with ssl=true, use HTTP_PORT otherwise
• ssl - (true/false) Whether to run on https:// with a TLS cert
• sslCertFileType - extension of TLS certificate file (crt/pem, default: crt)
• networkID - integer identifier of the network
  • The transactions are filtered by STRATO P2P based on this value if received from another networks
  • Datatype is BIGINT (up to 19 digits)
• PASSWORD - (Removed in STRATO v9.0) (Optional) STRATO Vault password
  • Once set the password is stored in memory for security reasons and needs to be re-entered on machine restart
  • If omitted, the administrator is asked to provide it as an input in STDIN
  • Should be omitted in production environments for security reasons (to avoid the password being kept in bash history and run scripts)
  • For more information about the password and the Vault refer to User Identity & Authorization - Key Vault
• validators - list of initial PBFT validator node addresses
  • Required for secondary nodes only
  • Default value: '[]'
  • Must contain root node's address
  • Format: '["validator_1_address"]' or for multiple validators: '["validator_1_address","validator_N_address"]')
  • For more information about validators and consensus, refer to PBFT Consensus
• blockstanbulAdmins - optional list of PBFT admin nodes which can cast votes to the node being deployed
  • Required for secondary nodes only
  • Default value: '[]'
  • When omitted (using the default value of empty list) - a node only accepts the votes from itself
  • Format: '["admin_node_1_address"]' or for multiple admins: '["admin_node_1_address","admin_node_N_address"]')
• OAUTH_DISCOVERY_URL - OpenID Discovery URL (aka "well-known URL") of Identity Provider (see Prerequisites)
• OAUTH_CLIENT_ID - Client ID configured on Identity Provider for the node being deployed
• OAUTH_CLIENT_SECRET - Client Secret for the Client ID provided
• OAUTH_JWT_USERNAME_PROPERTY - Property of JWT access token generated by Identity Provider to use as username
  • Default vaule: email
  • Other commonly used options are preferred_username, sub and others
• maxConn - The maximum number of client connections P2P will allow
  • Default value: 1000
• numMinPeers - How many other peers Ethereum-discovery will look for, which is the threshold for the service to stop querying for more peers.
  • Default value: 100
• VAULT_URL - URL of a deloyed STRATO Vault

Network Deployment Example

Following is a basic example of how to set up a STRATO network of 4 nodes (one root node, three secondary nodes) and vote-in the secondary nodes to PBFT consensus validators list.

• Node 1 - root node
• Nodes 2,3,4 - secondary nodes

Note

This example assumes that all the Prerequisites are met.

Prepare a Node

1. Clone STRATO Getting Started

   git clone https://github.com/blockapps/strato-getting-started
   cd strato-getting-started
   

2. Download the docker-compose.yml template of the latest STRATO version and pull the Docker images:

   ./strato --compose
   ./strato --pull
   

   Note

   You may need the root user permissions for ./strato script to access Docker daemon. Prepend ./strato with sudo or switch to super-user.

3. Copy your TLS key and certificate files into strato-getting-started/ssl (see Obtaining TLS certificate for additional information on TLS certificates):

   cp /path/to/server.pem ./ssl/certs/server.pem
   cp /path/to/server.key ./ssl/private/server.key
   

   Tip

   The certificate may be in pem or crt format. Make sure to provide the corresponding type in sslCertFileType configuration option in your run script.

Deploy Root Node

Assuming that the steps in Prepare a Node section are complete:

1. Create a run script for the root node. Use any editor of your choice:

   nano run.sh
   

   Paste:

   #!/usr/bin/env bash
   sudo \
     NODE_HOST="node-1.example.com:8080" \
     HTTPS_PORT='8080' \
     isRootNode=true \
     OAUTH_DISCOVERY_URL='https://<identity_provider_url>/.well-known/openid-configuration' \
     OAUTH_CLIENT_ID='<identity_provider_client1_id>' \
     OAUTH_CLIENT_SECRET='<identity_provider_client1_secret>' \
     OAUTH_JWT_USERNAME_PROPERTY='<identity_provider_jwt_username_property>' \
     VAULT_URL='https://<vault_hostname>:<vault_port>' \
     ssl=true \
     sslCertFileType='pem' \
     networkID=1234567890 \
     ./strato --blockstanbul
   

   Boot node IP

   It is useful to add the BOOT_NODE_IP option to the root node's run script if the IP of any of the future secondary nodes is known. This will be required in the future if you upgrade and re-sync the root node with the network.

   Set the executable permissions to the script:

   chmod +x run.sh
   

2. Execute the script:

   ./run.sh
   

   This should start the STRATO containers.

3. Set the Vault password by providing it in the shell input:

   Tip

   In dev environments, add the PASSWORD='your_password' configuration option to skip the manual input (e.g. for automated programmatic deployments).

   !!! Warning 'Re-enter the password after restart' The Vault password needs to be manually re-entered after each Vault container restart (VM restart, Docker service restart etc.)

4. Once the node is deployed, get the node's blockchain address:

   ./strato --get-address
   

   Keep it for the secondary node scripts in the further steps.

5. (Optional) You can check if your node is deployed properly by:

   • Checking docker ps output to see if all containers with health checks are healthy
   • Opening the node's URL (https://node-1.example.com:8080) in browser and logging in with identity provider user's credentials and checking:
     • If the node's health is green on the main dashboard page
     • If the new block was created on your first time login (the number of blocks should increment on the main dashboard page)

   Debugging Node Health

   In case of the problems with node's health, start debugging by checking the detailed health information on the API endpoint GET /apex-api/status. For more information, refer to STRATO API Reference

Deploy Secondary Nodes

The steps to deploy all secondary nodes are similar and can be executed on all secondary nodes in parallel.

Assuming that the steps in Prepare a Node section are complete:

1. Create a run script on each of the secondary nodes. Use any editor of your choice:

   nano run.sh
   

   Paste the script. Edit the data specific for each node (NODE_HOST and identity provider information).

   Identity Provider

   The nodes do not necessarily need to use the same identity provider. Each node may have its own provider.

   #!/usr/bin/env bash
   sudo \
     NODE_HOST="node-N.example.com:8080" \
     HTTPS_PORT='8080' \
     BOOT_NODE_IP='<IP_of_the_root_node>' \
     validators='["<address_of_the_root_node>"]' \
     blockstanbulAdmins='["<address_of_the_root_node>"]' \
     OAUTH_DISCOVERY_URL='https://<identity_provider_url>/.well-known/openid-configuration' \
     OAUTH_CLIENT_ID='<identity_provider_clientN_id>' \
     OAUTH_CLIENT_SECRET='<identity_provider_clientN_secret>' \
     OAUTH_JWT_USERNAME_PROPERTY='<identity_provider_jwt_username_property>' \
     VAULT_URL='https://<vault_hostname>:<vault_port>'  \
     ssl=true \
     sslCertFileType='pem' \
     networkID=1234567890 \
     ./strato --blockstanbul
   

   Set the executable permissions to the script:

   chmod +x run.sh
   

2. Execute the script:

   ./run.sh
   

   This will start the STRATO containers.

   Note

   The secondary nodes can be started in parallel - all at the same time.

   Note

   For versions of STRATO prior to v9.0, if asked, set the Vault password by providing it in the shell input.

3. Once the node is deployed, get the node's blockchain address:

   ./strato --get-address
   

   Keep it for the further steps to make secondary nodes the validators.

   You can check the health of the node and the network by following step 5 in Deploy Root Node

At this point we have the running 4-node STRATO network with only one node (Node 1 / root node) being the validator.

Follow the steps in Validators section to make the rest of the nodes the validators (to participate in consensus).

Deploy Central Monitoring Dashboard

It is recommended to deploy the Central Monitoring Dashboard (CMD) to monitor your STRATO network's health. For details, refer to Central Monitoring Dashboard (CMD)