Setting up the server

The pmesh setup command is used to configure the network settings for the node. This can be used to setup any kind of topology, from a single node to a full mesh. You will need to run this command before starting the server for the first time.

Node types

If you are running a local development server, you will want to create a seed server since you are the first node in the network, but for the production server, there are many options to choose from.

Seed server

pmesh setup seed

Used for your very first server, it will be used to bootstrap the network as the first leader of the RAFT topology.

Full node

pmesh setup join

Full member of a mesh similar to a seed server, but it needs to join an existing mesh. Typically this should be used for long-running servers as they can be elected as the leader.

Light replica

pmesh setup replica

Light replica of a mesh, holds a copy of the state to serve locally, but does not participate in elections. This is useful for read-only replicas or for servers that are not always online.

Client

pmesh setup client

Used for clients that want to connect to the services on the mesh, but do not participate in the topology. This can be used for any ephemeral service that needs to connect to the mesh, or if you wish to run the NATS.io server yourself.

Under the hood

The configuration you provide is used to setup the NATS cluster which are typically quite a bit more cumbersome. For starters, NATS will reject to run a cluster of size one, meaning if you want to scale to two servers, you will need to take down the first server to join the second one. It will also not tolerate any fault in the network until you have at least three nodes, so if your second server goes down, you are now offline.

To take care of this, pmesh uses a fork of the project with the necessary changes to make it work out of the box. Additionally, the NATS configuration is generated automatically, placing the servers nearby in the same cluster, and connecting the rest using supercluster gateways. It will also update itself as you connect new servers so this becomes a set-and-forget operation.

Example

Let’s setup a new server as a seed server using the interactive setup command for our local development environment.

pmesh setup

Changing the configuration

The setup command will create a settings.json file in the ~/.pmesh directory. To make changes or fetch a value, you can use the pmesh get and pmesh set commands.