Networks & Federations

There are several ways to setup a network. You can use the Kubernetes deployment template in this section, or use the Ansible solution in the Contributing section. Also, you can setup a single node on your machine and connect to an existing network.

Planetmint Networks

A Planetmint network is a set of connected Planetmint nodes, managed by a Planetmint consortium (i.e. an organization). Those terms are defined in the Planetmint Terminology page.

Consortium Structure & Governance

The consortium might be a company, a foundation, a cooperative, or some other form of organization. It must make many decisions, e.g. How will new members be added? Who can read the stored data? What kind of data will be stored? A governance process is required to make those decisions, and therefore one of the first steps for any new consortium is to specify its governance process (if one doesn’t already exist). This documentation doesn’t explain how to create a consortium, nor does it outline the possible governance processes.

It’s worth noting that the decentralization of a Planetmint network depends, to some extent, on the decentralization of the associated consortium. See the pages about decentralization and node diversity.

DNS Records and SSL Certificates

We now describe how we set up the external (public-facing) DNS records for a Planetmint network. Your consortium may opt to do it differently. There were several goals:

• Allow external users/clients to connect directly to any Planetmint node in the network (over the internet), if they want.

• Each Planetmint node operator should get an SSL certificate for their Planetmint node, so that their Planetmint node can serve the Planetmint HTTP API via HTTPS. (The same certificate might also be used to serve the WebSocket API.)

• There should be no sharing of SSL certificates among Planetmint node operators.

• Optional: Allow clients to connect to a “random” Planetmint node in the network at one particular domain (or subdomain).

Node Operator Responsibilities

1. Register a domain (or use one that you already have) for your Planetmint node. You can use a subdomain if you like. For example, you might opt to use abc-org73.net, api.dynabob8.io or figmentdb3.ninja.

2. Get an SSL certificate for your domain or subdomain, and properly install it in your node (e.g. in your NGINX instance).

3. Create a DNS A Record mapping your domain or subdomain to the public IP address of your node (i.e. the one that serves the Planetmint HTTP API).

Consortium Responsibilities

Optional: The consortium managing the Planetmint network could register a domain name and set up CNAME records mapping that domain name (or one of its subdomains) to each of the nodes in the network. For example, if the consortium registered bdbnetwork.io, they could set up CNAME records like the following:

• CNAME record mapping api.bdbnetwork.io to abc-org73.net

• CNAME record mapping api.bdbnetwork.io to api.dynabob8.io

• CNAME record mapping api.bdbnetwork.io to figmentdb3.ninja

How to Set Up a Planetmint Network

You can setup or connect to a network once you have a single node running. Until now, everything could be done by a node operator, by themselves. Now the node operators, also called Members, must share some information with each other, so they can form a network.

There is one special Member who helps coordinate everyone: the Coordinator.

Member: Share hostname, pub_key.value and node_id

Each Planetmint node is identified by its:

• hostname, i.e. the node’s DNS subdomain, such as bnode.example.com, or its IP address, such as 46.145.17.32

• Tendermint pub_key.value

• Tendermint node_id

The Tendermint pub_key.value is stored in the file $HOME/.tendermint/config/priv_validator.json. That file should look like:

{
  "address": "E22D4340E5A92E4A9AD7C62DA62888929B3921E9",
  "pub_key": {
    "type": "tendermint/PubKeyEd25519",
    "value": "P+aweH73Hii8RyCmNWbwPsa9o4inq3I+0fSfprVkZa0="
  },
  "last_height": "0",
  "last_round": "0",
  "last_step": 0,
  "priv_key": {
    "type": "tendermint/PrivKeyEd25519",
    "value": "AHBiZXdZhkVZoPUAiMzClxhl0VvUp7Xl3YT6GvCc93A/5rB4fvceKLxHIKY1ZvA+xr2jiKercj7R9J+mtWRlrQ=="
  }
}

To get your Tendermint node_id, run the command:

tendermint show_node_id

An example node_id is 9b989cd5ac65fec52652a457aed6f5fd200edc22.

Share your hostname, pub_key.value and node_id with all other Members.

Coordinator: Create & Share the genesis.json File

At this point the Coordinator should have received the data from all the Members, and should combine them in the file $HOME/.tendermint/config/genesis.json:

{
   "genesis_time":"0001-01-01T00:00:00Z",
   "chain_id":"test-chain-la6HSr",
   "consensus_params":{
      "block_size_params":{
         "max_bytes":"22020096",
         "max_txs":"10000",
         "max_gas":"-1"
      },
      "tx_size_params":{
         "max_bytes":"10240",
         "max_gas":"-1"
      },
      "block_gossip_params":{
         "block_part_size_bytes":"65536"
      },
      "evidence_params":{
         "max_age":"100000"
      }
   },
   "validators":[
      {
         "pub_key":{
            "type":"tendermint/PubKeyEd25519",
            "value":"<Member 1 public key>"
         },
         "power":10,
         "name":"<Member 1 name>"
      },
      {
         "pub_key":{
            "type":"tendermint/PubKeyEd25519",
            "value":"<Member 2 public key>"
         },
         "power":10,
         "name":"<Member 2 name>"
      },
      {
         "...":{

         },

      },
      {
         "pub_key":{
            "type":"tendermint/PubKeyEd25519",
            "value":"<Member N public key>"
         },
         "power":10,
         "name":"<Member N name>"
      }
   ],
   "app_hash":""
}

Note: The above consensus_params in the genesis.json are default values.

The new genesis.json file contains the data that describes the Network. The key name is the Member’s moniker; it can be any valid string, but put something human-readable like "Alice's Node Shop".

At this point, the Coordinator must share the new genesis.json file with all Members.

Member: Connect to the Other Members

At this point the Member should have received the genesis.json file.

The Member must copy the genesis.json file into their local $HOME/.tendermint/config directory. Every Member now shares the same chain_id and genesis_time (used to identify the Network), and the same list of validators.

Each Member must edit their $HOME/.tendermint/config/config.toml file and make the following changes:

moniker = "Name of our node"
create_empty_blocks = false
log_level = "main:info,state:info,*:error"

persistent_peers = "<Member 1 node id>@<Member 1 hostname>:26656,\
<Member 2 node id>@<Member 2 hostname>:26656,\
<Member N node id>@<Member N hostname>:26656,"

send_rate = 102400000
recv_rate = 102400000

recheck = false

Note: The list of persistent_peers doesn’t have to include all nodes in the network.

Member: Start Tarantool

You install Tarantool as described here.

You can start it using the command tarantool.To run it in the background (so it will continue running after you logout), you can have to create a listener box.cfg{listen=3301}.

Member: Start Planetmint and Tendermint Using Monit

This section describes how to manage the Planetmint and Tendermint processes using Monit, a small open-source utility for managing and monitoring Unix processes. Planetmint and Tendermint are managed together, because if Planetmint is stopped (or crashes) and is restarted, Tendermint won’t try reconnecting to it. (That’s not a bug. It’s just how Tendermint works.)

Install Monit:

sudo apt install monit

If you installed the planetmint Python package as above, you should have the planetmint-monit-config script in your PATH now. Run the script to build a configuration file for Monit:

planetmint-monit-config

Run Monit as a daemon, instructing it to wake up every second to check on processes:

monit -d 1

Monit will run the Planetmint and Tendermint processes and restart them when they crash. If the root planetmint_ process crashes, Monit will also restart the Tendermint process.

You can check the status by running monit status or monit summary.

By default, it will collect program logs into the ~/.planetmint-monit/logs folder.

To learn more about Monit, use monit -h (help) or read the Monit documentation.

Check planetmint-monit-config -h if you want to arrange a different folder for logs or some of the Monit internal artifacts.

If you want to start and manage the Planetmint and Tendermint processes yourself, then look inside the file planetmint/pkg/scripts/planetmint-monit-config to see how it starts Planetmint and Tendermint.

How Others Can Access Your Node

If you followed the above instructions, then your node should be publicly-accessible with Planetmint Root URL https://hostname or http://hostname:9984. That is, anyone can interact with your node using the Planetmint HTTP API exposed at that address. The most common way to do that is to use one of the Planetmint Drivers.

Kubernetes Deployment Template

Note

A highly-available Kubernetes cluster requires at least five virtual machines (three for the master and two for your app’s containers). Therefore we don’t recommend using Kubernetes to run a Planetmint node if that’s the only thing the Kubernetes cluster will be running. Instead, see our Node Setup. If your organization already has a big Kubernetes cluster running many containers, and your organization has people who know Kubernetes, then this Kubernetes deployment template might be helpful.

This section outlines a way to deploy a Planetmint node (or Planetmint network) on Microsoft Azure using Kubernetes. You may choose to use it as a template or reference for your own deployment, but we make no claim that it is suitable for your purposes. Feel free change things to suit your needs or preferences.