Setting up the clustering extension

After following the steps to install and configure JDBCConfig and Clustering, your GeoServer configuration will be stored in a JDBC database. The following process will detail how to set up an initial cluster from this point. The specific network details will change depending on your system.


Make sure you have set the data directory to be external to the GeoServer installation, in a shared location that all GeoServer instances will be able to access.


Setting up a database for the data directory is a one-way process. It is not currently possible to export the configuration back to a file-based data directory.


Configuration of the clustering extension, as it involves changes to the data directory, must be done through configuration files. It cannot be done through the UI. It is also not possible to use the REST API to configure the clustering extension.


This setup assumes that a load balancer (such as HAProxy will be employed in front of GeoServer. The details of the configuration of the load balancer are beyond the scope of this documentation.

Broadcasting setup

  1. Open the file <data_dir>/cluster/ in a text editor.

  2. Replace the lines:


    with the lines:

  3. Save and close this file.


  1. Start GeoServer and log in as an administrator to the web interface.

  2. If the clustering extension is working, you will see two messages on the Welcome page: one about JDBCConfig and the other about clustering.


    JDBCConfig status


    Clustering status

  3. Confirm that the JDBC message lists the correct JDBC URL. Also confirm that the layers, stores, and other catalog objects have been imported correctly by viewing the list and them in the Layer Preview.

Other nodes

To configure the other GeoServer nodes, perform the following steps on each:

  1. Install GeoServer with the clustering extension. Make sure that it is responding on the same subnet as the initial GeoServer.


    Alternately, you can convert the edited GeoServer instance to a WAR and then deploy it.

  2. Point the new GeoServer instance to the shared data directory.

  3. Restart the new GeoServer. Verify that the extension is working properly and that the node is reading the shared data directory.

Session sharing

(Optional but recommended) HTTP session sharing is not enabled by default. To enable session sharing:

  1. Open the file $CATALINA_HOME/webapps/geoserver/WEB-INF/web.xml in a text editor.

  2. Add this block of text as the first filter in the file.


    The order is very important here. This must come first.

  3. Add the following block of text as the very first filter-mapping in the file.


    Again, the order is very important.

  4. Add the following block of text in the listener section. The order is not important here.

    <!-- hazelcast session listener -->
  5. Restart GeoServer.

Repeat this for each GeoServer in the cluster.

Log separation

By default, a cluster will end up collecting all the log output from all the nodes into a single file without indicating which message came from which node.

If this is not desired, you can split the logs into files distinct to each node. This property can be set via the standard methods of a JVM system variable, environment variable, or servlet context parameter.

The variable to set is called GEOSERVER_LOG_LOCATION:


Or, as set in web.xml:


For example, on GeoServer node #1, you could set the following variable:


For node #2:


This way, each node will have its own log in the shared data directory, making administration and troubleshooting easier.

Final verification

To verify that the cluster is set up correctly, perform the following steps:

  1. If you enabled session sharing, log in to GeoServer through the load balancer, shut down the node that handled the login request, then make subsequent requests and verify that you are still logged in.

  2. On the first instance, view a layer (through the Layer Preview).

  3. On the second instance, make a change to the layer, such as one that will affect its visualization or metadata (Title or Abstract). Save this change.

  4. Verify that the change has propagated back to the first instance.


    Perform this step quickly so as to ensure that it is the clustering extension that is working as expected, and not just as a result of cache expiration.

Repeat these steps for other instances until all nodes in the cluster have been tested against one other node.