On this page

Quick start: Webserver cluster

This page builds a cluster of two Webservers and one witness, starting from a Webserver that already runs (or a new one). Allow about thirty minutes. Your data, users and monitors are kept.

Before you start

You need Detail
3 hosts Two for the Webservers, one small host for the witness. They must reach each other on one TCP port of your choice (7001 here).
A shared address A virtual IP, a load balancer or a DNS name in front of the two Webservers. Users and components use it instead of a node’s own address.
A cluster license One license_MNS.dat that lists both Webservers. See step 1.
Synchronised clocks NTP on the three hosts.
The Webserver package The same release on the three hosts, one that includes the cluster feature (later than 4.2.0).

The commands use these example values. Replace them with yours.

Value Example
Node 1: the Webserver that holds your data 10.0.0.11, name node1
Node 2: the second Webserver 10.0.0.12, name node2
Witness 10.0.0.13, name witness
Cluster port 7001
Shared address mugnsoft.example.com
Install folder /opt/mugnsoft/webserver

Windows

The steps are the same. Use webserver.exe instead of ./webserver, in an elevated PowerShell, from C:\Mugnsoft\webserver.

Step 1: get the cluster license

Run the fingerprint tool on node 1 and node 2 and send both tokens to Mugnsoft, saying which one is node 1. You receive one license_MNS.dat for the cluster. The witness needs no license.

List first the server that holds your data: the first server of the license has extra rights, see License.

Step 2: generate the cluster key

On node 1, from the install folder:


cd /opt/mugnsoft/webserver
./webserver ha genkey

It prints 64 hexadecimal characters. This key is the same on the three nodes: it is what lets them trust each other. Keep it secret.

Step 3: turn node 1 into the first cluster node

No Webserver yet? Install one first with Install on Linux or Install on Windows, using the cluster license, then come back here.

  1. Stop the service and install the cluster license:

./webserver stop
cp /path/to/license_MNS.dat /opt/mugnsoft/webserver/
  1. Edit webserver.json: keep what is there and add AdvertiseAddress and the HA block.

{
  "HTTPS": "true",
  "PortAPI": "8050",
  "PortWEB": "9090",
  "AdvertiseAddress": "mugnsoft.example.com",
  "HA": {
    "NodeID": "node1",
    "Bind": "10.0.0.11:7001",
    "Key": "<the cluster key>",
    "Bootstrap": "true",
    "Peers": ["10.0.0.12:7001", "10.0.0.13:7001"]
  }
}

Peers lists the two other nodes, not this one. Bootstrap goes on node 1 only.

  1. Start it and check:

./webserver start
./webserver ha status

Node 1 is the active Webserver, alone for now, with all its data. The UI works as before.

Step 4: add node 2

  1. On node 2, download and extract the Webserver package (step 1 of Option B in Install on Linux). Do not install or start it yet.
  2. Copy the same cluster license into the install folder.
  3. Copy the TLS certificate and its key from node 1, so both Webservers present the same certificate:

mkdir -p config/ssl/certificates config/ssl/private
scp 10.0.0.11:/opt/mugnsoft/webserver/config/ssl/certificates/webserver.pem config/ssl/certificates/
scp 10.0.0.11:/opt/mugnsoft/webserver/config/ssl/private/webserver.key     config/ssl/private/
  1. Write webserver.json: the same shared address and key, its own name and address, no Bootstrap.

{
  "HTTPS": "true",
  "PortAPI": "8050",
  "PortWEB": "9090",
  "AdvertiseAddress": "mugnsoft.example.com",
  "HA": {
    "NodeID": "node2",
    "Bind": "10.0.0.12:7001",
    "Key": "<the cluster key>",
    "Peers": ["10.0.0.11:7001", "10.0.0.13:7001"]
  }
}
  1. Install the service and start it:

./webserver install && ./webserver start

Node 2 copies the data from node 1, then joins as a standby. On a large installation the copy takes a few minutes.

Step 5: add the witness

On the witness host, extract the same package. No license, no certificate to copy. Write webserver.json:


{
  "HTTPS": "true",
  "PortAPI": "8050",
  "PortWEB": "9090",
  "HA": {
    "NodeID": "witness",
    "Bind": "10.0.0.13:7001",
    "Key": "<the cluster key>",
    "Witness": "true",
    "Peers": ["10.0.0.11:7001", "10.0.0.12:7001"]
  }
}

Then:


./webserver install && ./webserver start

The witness votes and holds a copy of the data. It runs no web server: nobody connects to it.

Step 6: check the cluster

On any node:


./webserver ha status

It lists the three nodes and tells which one is active.

In the UI: gear menu → components, edit the Webserver. The High availability cluster panel must show Healthy, with node 1 active, node 2 on standby and the witness.

The panel shows Meaning
Healthy Three nodes up and in sync.
Joining A node is still copying the data. Wait.
Check needed Something would go wrong at the next failover. The panel says what and on which server. See Troubleshooting.

Step 7: put the shared address in front

Point the virtual IP or load balancer at both Webservers (not the witness), on the WEB and API ports, with this health check:

Check Active node Standby
GET /ha/health 200 503

The health check is what steers clients away from a node that is down. A request that reaches a standby is not lost either: the standby passes it to the active node.

From now on, users browse to https://mugnsoft.example.com:9090/.

Step 8: check the components

Nothing has to be registered again. The components, their certificates and their tokens are part of the data both Webservers hold.

Component What to do
Sentinel agents Nothing. The active Webserver tells each agent the shared address. The agent switches once it has checked that it reaches it.
Probes Nothing. The Webserver calls them.
Integrators Set webserverUrl to https://mugnsoft.example.com:9090 in integrator.json and restart, so the links in notifications open the shared address.
Firewalls Each Webserver calls the components from its own IP. Allow node 2 wherever node 1 was allowed.
New components Register them with the shared address: --webserver mugnsoft.example.com:8050. The guided tour and the config builder already give it.

Details in Configuration.

Step 9: test a failover

  1. Stop the active Webserver:

# on node 1
./webserver stop
  1. Reload the UI through the shared address. It answers within seconds and you are still logged in. The cluster panel shows node 2 active and node 1 down.
  2. Start node 1 again. It catches up on its own and becomes a standby. The role does not move back: node 2 stays active.

./webserver start
./webserver ha status

Next

  • Operations: maintenance, replacing a node, recovering when nodes are lost.
  • License: what happens when a single Webserver is left.
  • How it works: what is copied between the nodes and what is not.

Translations

How it works