#Cluster Deployment

The support of cluster deployment of Webswing is new in version 20.2. This guide will help you setup your cluster and present the main features and concepts of Webswing Cluster.

#Overview

The main concept of clustered Webswing is to divide the former Webswing Server into separate modules which handle web requests (Webswing Cluster Server) and application processing (Webswing Session Pool). In addition Admin console with its REST interface has been extracted into Admin Console Server module. With this setup you are able to deploy one Webswing cluster, handling multiple applications with:

• 1 .. N Webswing Cluster Servers
• 1 .. N Webswing Session Pools
• 0 .. 1 Webswing Admin Console Server

In a minimal setup you need 1 Cluster Server and 1 Session Pool. You can use multiple Cluster Servers for redundancy, but it should not be necessary to have more than 2 Cluster Servers in most cases. Session Pools can be scaled dynamically, depending on your needs of resources or connected users. Note that it is not possible to connect more than 1 Admin Console Server in the cluster.

You can deploy your cluster manually in a static way or you can use Docker images and Kubernetes with custom auto-scaling. For more information about Docker and Kubernetes deployment please contact support@webswing.org.

#Installation

To install Webswing Cluster first unzip the distribution zip file. In the folder you will find webswing.war archive, which is used to start both Cluster Server and Session Pool. There is a separate startup script for each module. To simplify your deployment, you can make a copy of the unzipped distribution folder for each module (Cluster Server or Session Pool) you want to deploy and start the module accordingly, using webswing.sh/webswing.bat for Cluster Server or sessionpool.sh/sessionpool.bat for Session Pool.

If you are using a headless Linux with X virtual frame buffer (Xvfb), xvfb is needed only in case of Session Pool.

It is highly recommended that you do not share the configuration files between multiple modules. Every Cluster Server and every Session Pool should at least have its own *.config file. If you plan to have multiple Cluster Servers or Session Pools, create a separate installation folder for each of them. Also consider using Docker images which can easily contain your single module deployments.

#Cluster Server

Cluster Server is similar to Webswing Server with the difference that it is not able to start an application instance itself. Therefore it is a lightweight module, which basically resends messages between application instance and browser. It also decides on which Session Pool the instance will be started, holds session statistics and metrics for Admin Console Server and does some other necessary communication with Session Pools.

Cluster Server is a stateless web server, which means that if you have multiple Cluster Servers it doesn't matter which server you connect to from the browser, even on refresh, the browser connection will always find the way to its application instance. If you have multiple Cluster Servers deployed and one of the Cluster Servers terminate, all the browser connections to this server can be reconnected through the other running Cluster Server without terminating the application instance.

Inside Cluster Server is a built-in mechanism - a Session Pool load balancer. This mechanism is responsible for finding a free Session Pool where a new instance will be started. By default the load balancer uses a simple round-robin algorithm. If you need a more specific algorithm, e.g. for Session Pool scaling, please contact support@webswing.org.

Everything in your application that is related to web is configured and provided through the Cluster Server. This includes security (SSL, authentication, logout), translations, fonts or custom web resource handling. On the other hand, everything related to your application binary is configured and handled in Session Pool. Because of this the webswing.config file needs to be divided into 2 separate configuration files - webswing-server.config which is used by Cluster Server and webswing-app.config which is used by Session Pool. You can read more about this in next sections.

Cluster Server installation includes:

• webswing.war
• webswing-server.config
• jetty.properties
• webswing.properties
• webswing.bat / webswing.sh
• ssl configuration
• security module configuration / libs
• lang
• web related files for apps, e.g. custom index.html

Here is an example of a webswing-server.config file:

{
  "/" : {
    "path" : "/",
    "security" : {
      "module" : "EMBEDED",
      "config" : {
        "users" : [ {
          "username" : "admin",
          "password" : "pwd",
          "roles" : [ "admin" ]
        }, {
          "username" : "support",
          "password" : "pwd",
          "roles" : [ "support" ]
        }, {
          "username" : "user",
          "password" : "pwd"
        } ]
      },
      "classPath" : [ ]
    },
    "langFolder" : "${webswing.configDir}/lang",
    "homeDir" : "${user.dir}",
    "allowedCorsOrigins" : [ "*" ],
    "dataStore": {
    	"module": "FILESYSTEM",
    	"config": {
			"threadDumpsFolder": "C:/work/dataStore/threadDumps",
			"recordingsFolder": "C:/work/dataStore/recordings",
			"transferFolder": "C:/work/dataStore/transfer"
    	}
    }
  },
  "/swingset3" : {
    "path" : "/swingset3",
    "name" : "SwingSet3",
    "webFolder" : "${webswing.rootDir}/apps/SwingSet3/webroot",
    "security" : {
      "module" : "INHERITED",
      "config" : null,
      "classPath" : [ ]
    },
    "icon" : "${webswing.rootDir}/apps/SwingSet3/icon.png",
    "webHomeDir" : "${webswing.rootDir}/apps/SwingSet3",
    "langFolder" : "${webswing.configDir}/lang",
    "uploadMaxSize" : 5,
    "maxClients" : 100,
    "sessionMode" : "CONTINUE_FOR_BROWSER",
    "allowStealSession" : true,
    "autoLogout" : true
  }
}

Configuration of a Cluster Server is similar to the configuration of Webswing Server, please refer to this section for configuration options in webswing.properties.

#Session Pool

Session Pool is a simple JAR application. The main purpose of this module is to start, manage and communicate with an application instance. It connects to a Cluster Server via a WebSocket and it is always connected to all Cluster Servers in the Cluster. It is not desired that there is a connection problem between a Session Pool and a Cluster Server and this kind of problem should be resolved ASAP.

Unlike Cluster Server, Session Pool is stateful. When a Session Pool encounters a fatal error which leads to termination, all of the application instance processes that this Session Pool has created will be terminated as well.

Session Pool can be configured using webswing-sesionpool.properties file. The table below describes the properties used in the file.

Cluster Session Pool handles everything related to the application instance, therefore it needs access too application binaries, libraries, fonts and application configuration (webswing-app.config).

Cluster Session Pool installation includes:

• webswing.war
• webswing-app.config
• webswing-sessionpool.properties
• sessionpool.bat / sessionpool.sh
• application jar binaries and libraries
• fonts

Here is an example of a webswing-app.config file:

{
  "/swingset3" : {
	"jreExecutable" : "${java.home}/bin/java",
	"javaVersion" : "${java.version}",
	"vmArgs" : "-Xmx128m -DauthorizedUser=${user}",
	"classPathEntries" : [ "${webswing.rootDir}/apps/SwingSet3/SwingSet3.jar", "${webswing.rootDir}/apps/SwingSet3/*.jar" ],
	"theme" : "Murrine",
	"fontConfig" : {
	  "dialog" : "${webswing.configDir}/fonts/Roboto-Regular.ttf",
	  "dialoginput" : "${webswing.configDir}/fonts/RobotoMono-Regular.ttf",
	  "serif" : "${webswing.configDir}/fonts/RobotoSlab-Regular.ttf"
	},
	"swingSessionTimeout" : 300,
	"isolatedFs" : true,
	"debug" : true,
	"javaFx" : true,
	"javaFxClassPathEntries" : [ "${webswing.rootDir}/apps/javafx/*.jar" ],
	"directdraw" : true,
	"compositingWinManager" : true,
	"allowDelete" : true,
	"allowDownload" : true,
	"allowAutoDownload" : true,
	"allowUpload" : true,
	"allowJsLink" : true,
	"jsLinkWhitelist" : [ "org.webswing.demo.jslink.JsLinkDemo.*" ],
	"launcherType" : "Desktop",
	"launcherConfig" : {
	  "mainClass" : "com.sun.swingset3.SwingSet3",
	  "args" : null
	},
	"userDir" : "${user}",
	"homeDir" : "${webswing.rootDir}/apps/SwingSet3",
	"transparentFileSave" : true,
	"clearTransferDir" : true,
	"transparentFileOpen" : true,
	"transferDir" : "${user}/upload"
  }
}

#Migration of webswing.config

If you are migrating from version older than 20.2, you need to make some changes to your webswing.config file in order to use it in Webswing Cluster. First thing you should do is run Webswing Server 20.2 (non-cluster version) with your old webswing.config file. Once the server is started and the configuration is loaded, the config file automatically converts to a newer version and is stored. In version 20.2 some of the fields are moved from "swingConfig": {...} to app root (web config), e.g. "/swingset3": {}.

Having this webswing.config converted to a new version, you can create configuration files used in Cluster. Rename webswing.config to webswing-server.config and create new empty webswing-app.config file.

In webswing-app.config file create the structure of application paths like in this example:

{
	"/swingset3": {

	},
	"/javafx": {
	
	}
}

Now cut content from webswing-server.config from "swingConfig":

{
	"/swingset3": {
		"swingConfig": {
			<cut this>
		}
	}
}

and paste into the created structure in webswing-app.config:

{
	"/swingset3": {
		<paste here>
	}
}

Note that in webswing-app.config you do not provide any configuration for root path "/".

After you have cut and pasted all your application configurations into webswing-app.config, you can remove empty "swingConfig" fields from webswing-server.config. The configuration that is left in this file is your webswing-server.config.

#Admin Console

Please refer to this guide for more information about Admin Console setup. The only difference in Cluster is that you need to provide websocket URLs for all Cluster Servers in your deployment.

#Security

Modules inside your Cluster deployment are connected through WebSocket. To make sure that no other malicious servers connect to your Cluster Servers, all modules must share the same secret key which is used in handshake when establishing the websocket communication. The secret key is defined in webswing.properties, webswing-sessionpool.properties and webswing-admin.properties as property webswing.connection.secret. Please change this secret key to your random value before going into production. This secret key is also used for signing JWT tokens that are used for user session cookies. Make sure you use only alphanumeric characters in the secret key, please do not use any special characters.

#Data Store

Some of the data that application uses or produces must be available in different parts of the cluster (Session Pool, Cluster Server). This includes transfer (upload, download), thread dumps and recordings. Data store is a single point of access to these data. It is configurable in server (web) config and is inheritable similar to security module configuration. Default implementation is the FILESYSTEM data store module. If you need to implement another way of storing data in your cluster (e.g. in database) please contact support@webswing.org.

The easiest way to configure data store in your Cluster is to map a shared folder that is accessible by every module (Cluster Server, Session Pool) in your Cluster.

#Using Admin Console

#Cluster Overview

The main benefit of having an Admin Console in your Cluster is that you can see the cluster overview. In this view you can see which applications you have deployed on which Session Pools and how many users are connected.

#Sessions Overview

In the sessions overview you can see all sessions from the whole Cluster.

#Web Configuration

In configuration view you can manage your configurations on Cluster Servers (webswing-server.config) and Session Pools (webswing-app.config).

Note that if you are using multiple Cluster Servers, Web Configuration (webswing-server.config) must be identical on all Cluster Servers, because they are stateless. Therefore you see only one configuration form for Web Configuration and when you save your changes it is propagated and stored on each Cluster Server.

#App Configuration

Unlike Web Configuration, App Configurations can be different per Session Pool. If you are using multiple Session Pools you can select one and create a different configuration. This is in most cases not recommended as you could lose track of what is configured where, but you can use this possibility for A/B testing. If you want to update all Session Pool configurations at once, simple make your changes in the default All Session pools tab and the changes will be propagated and stored on each Session Pool.

You can also decide that you want to dedicate a Session Pool to a single application. In this case, you can simply turn on/off a Session Pool in the App Configuration Session Pool selector. Note that this will not only "disable" the application in the Session Pool but will also delete the app configuration from Session Pool's webswing-app.config. If you enable the application in the Session Pool again, the configuration values fallback to defaults. The recommended way is to prepare this kind of configuration of Session Pool before actually running it.

#REST interface

If you previously used Webswing REST interface from Webswing Server, you now need to point your requests to Admin Console Server. The REST interface has been moved to this module and Cluster Server nor Session Pool provide this service.