Geocortex Core and Clustering

Geocortex Essentials 4.6 and newer requires an instance of Geocortex Core version 3.0 or newer.

As of Geocortex Core 3.1.7, the default whitelist configuration has been tightened to improve security. Specifically, the WatcherHost setting is now set to * instead of _site_ by default, which means only requests from whitelisted IPs are allowed instead of allowing all requests from the local network. For more information, see Protecting Geocortex Core from Unwanted Access.

If you have multiple instances of Essentials that will belong to a cluster in a highly available environment, ensure that each instance has the same instance name, or that the instances are all unnamed. This allows the instances of Essentials to function as a unit. You may run into configuration issues if the instances use different names.

Benefits of Clustering

When you cluster instances of Core across multiple servers, you get the power and performance of multiple servers with a centralized data store. This makes managing and configuring your Geocortex products more straightforward, especially in complex deployments that receive a lot of traffic. Specifically, the benefits include:

We recommend that you run Geocortex Core in a three-node cluster to ensure data integrity.

Prerequisites for Core Clustering

The following should be available in preparation for clustering your servers:

Cluster your Instances of Core across Multiple Servers

To cluster your instances of Core across multiple servers:

  1. Install Geocortex Essentials on your first server.

    (Alternatively, upgrade an existing Geocortex Essentials instance to the newest version.)

  2. Continue the installation process to install Geocortex Core on the first server.

    (Alternatively, upgrade your existing instance of Core 2.x to Core 3.0.)

    1. On the Configure Cluster Information page in the installation wizard, choose the I want to create a new cluster option.

      If you are upgrading from an older version of Core, a cluster name is already present. Take note of the cluster name. All of the instances of Core that you install will be clustered using this same cluster name.

    2. Enter a shared secret for the cluster.

      Other instances of Core use this shared secret to join the cluster.

    3. Finish the Core installation.

  3. Install Geocortex Essentials on your other servers using the Custom installation option and excluding Essentials Manager (previously known as REST Manager) from the installation.

    During each installation process, the Core installer runs.

    1. On the Configure Cluster Information page in the installation wizard, choose the I want to join an existing cluster option.

      If you need to specify a specific host name or port that the existing cluster runs on, select the Advanced checkbox to manually enter this information.

    2. From the drop-down menu, choose the existing cluster from the other machines running Geocortex Core on your network.

    3. Enter the shared secret for the cluster that you created during Step 2.

    4. Finish the Core installation.

If your Analytics hub and Essentials instance are installed on the same server, they share a single instance of Core and do not require additional Core configuration.

If you have a virtual machine (VM) as part of your cluster, it often has the option of capturing a snapshot and restoring from the backup. Using a VM to take a snapshot and then rolling it back can cause a cluster to lose data. If you start the rolled back node first, you will almost certainly lose all the data that has accrued since the snapshot. You should always use the Geocortex Index Backup Utility to back up clustered data.

For information about backing up and restoring a clustered deployment, see Back Up a Clustered Installation.

Update Web.config to Specify the Sites and Temp Folders on the File Share

  1. Create 2 folders on the file share: one for Sites, and one for the Essentials Temp directory.

    The identity that you run the EssentialsAppPool4 application pool under must be able to write to the Temp folder and read from the Sites folder. Similarly, the identity that you run the EssentialsAdministrationAppPool4 application pool under must be able to read and write to the Temp folder and the Sites folder.

  2. On the first server, edit the Web.config file for the REST application.

    The default location is:

    C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\REST\Web.config

  3. Locate the key gcx.io.fileSystem.path and edit the value to point to the UNC path for your file share.

    For example, change the default from:

    <add key="gcx.io.fileSystem.path" value="C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Sites" />

    to:

    <add key="gcx.io.fileSystem.path" value="\\myfileshare\Essentials\Sites" />

    substituting the value with the actual share value.

  4. Add a line below the changed key and type the following new app setting for the path to your Temp folder.

    <add key="gcx.io.tempFileManager.commonTempFolder" value="\\myfileshare\Essentials\Temp" />

    substituting the value with the actual share value.

    The Temp folder, like the Sites folder, needs to be available from all nodes in the cluster.

  5. Save the Web.config file.

  6. Repeat the steps to update the key value and the setting to the Temp folder on the second and third servers.

  7. On the node where you installed Essentials Manager, make the same changes to the Web.config file located by default in:

    C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Manager\Web.config

  8. Save the updated file.

  9. Copy the contents from your local Sites folder to the Sites folder on the file share.

To validate your changes, log into Essentials Manager, create a new site, and check that the site appears in the Sites folder on file share.

Check the REST endpoint on the other nodes in the cluster to verify that you can see the site from all nodes.

Set the URL for the Load Balancer using the Post Installation Configuration

You only need to complete the following steps on one server. Since the security store is shared across the cluster, the setting for one server applies to all of the servers in the cluster.

  1. Run the Post Installation Configuration on the node where you installed REST Manager.

  2. Click Configure Geocortex Essentials REST API in the navigation frame.

  3. Click the Hosts button.

  4. Add the URL that points to your load balancer.

  5. Click OK, then click Finish.

Additional Considerations in a Clustered-Server Implementation

This section includes the following topics:

Clustered-Server Upgrade Considerations

When upgrading Essentials, complete the following to maintain the availability of your sites:

  1. Set the load balancer to point to a single node, but not the node with Essentials Manager installed on it.

  2. Upgrade Essentials on the other two nodes.

  3. Set the load balance to point to the 2 upgraded nodes, excluding the node not upgraded.

  4. Run Essentials Manager to update the sites and viewer to the new version (if applicable).

  5. Upgrade the remaining node to the new version of Essentials.

Configure the Cluster's Minimum Master-Eligible Nodes

For this release, you must also manually configure the discovery.zen.minimum_master_nodes setting in elasticsearch.yml on each server in the cluster. Alternatively, we recommend that you contact Geocortex Support for our recommended configuration settings for your deployment. For a typical installation of Core, you can find elasticsearch.yml here:

C:\Program Files\Latitude Geographics\Geocortex Core\NSRoot\Geocortex\Core\Roles\DocumentStore\3.x.x.xxxx\elasticsearch-2.3.1\config\elasticsearch.yml

The subfolder 3.x.x.xxxx varies, depending on the exact version of Core that is installed on the server.

Your discovery.zen.minimum_master_nodes setting should be set according to the number of servers that belong to the cluster. The minimum number of master-eligible nodes should always be the majority of your nodes.

No matter how many servers belong to the cluster, you can calculate the optimal minimum number of nodes using this equation:

( n ÷ 2 ) +1

Where n is the number of master-eligible servers in the cluster. By default, all Essentials nodes are master-eligible. So, if you have three servers in a cluster, then the minimum number of master eligible nodes is two.

If you add or remove servers from your cluster, you need to reconfigure the discovery.zen.minimum_master_nodes setting on each of your servers.

To configure the cluster's minimum master-eligible nodes:

  1. In elasticsearch.yml, locate the line that reads:

    # discovery.zen.minimum_master_nodes: 3

    The # indicates that this line is a comment.

  2. Remove the # from the beginning of the line.

    discovery.zen.minimum_master_nodes: 3
  3. Change the setting to the minimum majority of master-eligible servers in your cluster.

    If you have three servers, then the minimum master-eligible setting should be 2:

    discovery.zen.minimum_master_nodes: 2
  4. Repeat these steps on each server.

    Every server needs to have the discovery.zen.minimum_master_nodes setting configured.

  5. Restart the Geocortex Core service on each server to enable the changes.

    Follow the instructions below to restart the service.

Restart the Geocortex Core Service

To restart the Geocortex Core service:

  1. On your server, open the Windows Task Manager.

    You can open the Task Manager by pressing the CTRL+ALT+DELETE and selecting Task Manager from the list of options that appear.

  2. Select the Services tab.

  3. Locate the service named Geocortex Core and stop it.

    You can stop the Geocortex Core service by right-clicking it and selecting Stop from the context menu.

  4. Restart the Geocortex Core service by right-clicking in and selecting Start from the context menu.

  5. Repeat these steps on all of the servers that belong to the cluster.

Loss of Connectivity in a Two-Server Cluster (Split-Brain Scenario)

If you have two Essentials instances clustered across two servers, loss of connectivity between the servers results in a "split-brain" scenario in which each server elects itself as master of the cluster and can write conflicting information to the database.

While solving this issue can be as simple as reconnecting and restarting the confused server and restoring your database from your last valid backup, a split-brain scenario always results in data loss. We strongly recommend adding a third clustered server to your deployment, which greatly reduces the risk of a split-brain scenario. Alternatively, you can avoid a split-brain scenario by deploying your applications to a single server.

To set up a third clustered server, we recommend that you install Geocortex Essentials on a third server. However, you do not need to maintain a third instance of Geocortex Essentials to have a third clustered server. Once you have run the Post-Installation Configuration and installed Core, you can uninstall Geocortex Essentials from the system if you wish.

Geocortex Core Backwards Compatibility with Essentials 4.4 and 4.5

If you are running Essentials 4.6 or newer but you need to maintain an instance of Essentials 4.4.x or 4.5.x, you can use the Geocortex Essentials Legacy Version Compatibility Tool to make Geocortex Essentials 4.4.x or 4.5.x compatible with Core 3.0. Without this tool, you cannot maintain your legacy instances of Essentials on the same server as, or as part of the same cluster of, Essentials versions that require Core 3.0.

You can find the tool on the Geocortex Support Center in the Essentials Downloads section.

The Geocortex Essentials Legacy Version Compatibility Tool does not work with versions of Geocortex Essentials older than 4.4.

To maintain a legacy version of Essentials while running an instance of Core 3.0:

  1. Download the Geocortex Essentials Legacy Version Compatibility Tool from the Geocortex Support Center.

    You can download the compatibility tool from the Essentials Downloads area the Geocortex Support Center.

  2. Run the Geocortex Essentials Legacy Version Compatibility Tool executable.

    A list of your Essentials instances appears.

  3. Use the Apply Patch button next to each Essentials instance you want to patch.

  4. Confirm that you want to apply the patch by selecting Yes on the Apply Patch dialog.

    The Essentials instance is patched.

  5. Exit the tool.

© 2019 Latitude Geographics Group Ltd. All Rights Reserved.

Documentation Version 4.11