#Webswing Installation Guide

Webswing is packaged and distributed as a fully working platform with some examples for your convenience, so no complicated installation is needed. Just unpack the distribution zip file and you are good to go. The only prerequisite is to have a supported version of Java installed.

Supported Java versions for starting server are

• All major distributions compliant with the Java SE 11 or 8 standards.

---

#Downloading the Webswing

First download Webswing or you can download other versions in Client Portal

#Starting on Windows

If you are using the Windows operating system, you can use the webswing.bat script, which executes the following command:

java -jar webswing-server.war -j jetty.properties

Note: Make sure java is pointing to a supported java version by running java -version from your commandline.

#Windows Service

To wrap Webswing as a windows service you can use https://nssm.cc

e:\nssm-2.24\win64>nssm install "Webswing 20.1" c:\webswing\webswing.bat 

Or you can run Webswing in Tomcat and setup Tomcat to run as a service.

https://tomcat.apache.org/tomcat-8.0-doc/windows-service-howto.html

You can also use different application server if you have internal preference and know-how. We recommend using headless Linux or Containerization which has less license, less OS overhead, better maintenance and support for running services. Keep reading below to find out how to run on Linux.

---

#Starting on Linux

Starting Webswing on a Linux desktop (within XServer) session is as simple as running the above command--the same as on Windows.

In most cases however, the Linux server is a headless box. In these cases you would get an error when running the above command, because the Swing framework requires a graphical environment. To overcome this, we can use X virtual frame buffer (Xvfb) to satisfy these dependencies.

Please install the following Linux packages to satisfy all Swing framework dependencies (names are from Ubuntu repositories - use relevant counterparts for your distribution):

• xvfb
• libxext6
• libxi6
• libxtst6
• libxrender1

The Webswing distribution contains a convenience Linux startup script - webswing.sh, which uses default startup settings.

export HOME=<webswing.sh location>
export OPTS="-h 0.0.0.0 -j $HOME/jetty.properties -u $HOME/user.properties -c $HOME/webswing.config"
export JAVA_HOME=$JAVA_HOME
export JAVA_OPTS="-Xmx128M" 

These may be overridden by setting the following environment variables:

• WEBSWING_HOME
• WEBSWING_OPTS
• WEBSWING_JAVA_HOME
• WEBSWING_JAVA_OPTS
• WEBSWING_LOG_FILE
• WEBSWING_PID_FILE

For example:

WEBSWING_HOME=/home/webswing WEBSWING_JAVA_HOME=/var/share/jdk8 ./webswing.sh start

When started, this script will create two additional files in the HOME folder (by default).

• webswing.pid storing the PID of current Webswing process
• webswing.out standard output and error is redirected to this file.

When running the script you have following options:

Usage: webswing.sh {run|start|stop|restart|status}

Command	Description
webswing.sh run	This command can be used to start Webswing if you are inside X session. This will block the terminal until the server stops.
webswing.sh start	Start Webswing as daemon in new Xvfb session using the xvfb-run command
webswing.sh stop	Stops running Webswing server
webswing.sh restart	Stops and starts Webswing server
webswing.sh status	Checks if Webswing server is running.

---

#Important files

Webswing distribution contains several files, but only three of them are necessary to run Webswing.

1. webswing-server.war file is the main executable file. This file is a regular Java web application archive with embedded jetty server.

2. webswing.config file contains the configuration of swing applications. Swing application's class-path, main class, arguments and permissions are described in this file. See more details in the "Application setup" section.

3. (optional)jetty.properties is a convenient option of configuring the built-in Jetty server. Each setting can be overridden with command-line option. For more details refer to the Server start-up parameters section.

Webswing generates the following output files:

tmp folder is created for extracting client libraries and temporary files generated by application print or file download functionality. The path for this temporary folder can be changed by defining command-line option -t <path> . By default tmp folder contents are wiped when Webswing starts. If -d true is set, a time-stamped folder inside tmp is created every time the Webswing server is started.

webswing.log file for storing Webswing server and swing application instance logs.

#Docker

Webswing Docker Repository

Supported tags:

• 20.1.8, 20.1.8_jre8
• 20.1.7, 20.1.7_jre8
• 20.1.6, 20.1.6_jre8
• 20.1.5, 20.1.5_jre8
• 20.1.4, 20.1.4_jre8
• 20.1.3, 20.1.3_jre8
• 20.1.2, 20.1.2_jre8
• 20.1.1, 20.1.1_jre8
• 20.1, 20.1_jre11, 20.1_jre8

Quick startup:

docker run -it --rm -p 80:8080 webswing/webswing-se:20.1

Docker Compose Example:

Create docker-compose.yml file:

version: "3.3"

services:
  webswing:
    image: webswing/webswing-se:20.1
    environment:
      - WEBSWING=/opt/app/config/webswing.config
    volumes:
      - /opt/app:/opt/app
    ports:
      - "80:8080"

Environment variable WEBSWING specifies where your config file is. Volume syncs container with host, so your config survives the restart of container. Docker ports are of "host:container" syntax. So with "80:8080" your app will be accessible without specifying port number.

On your host create folder /opt/app and place there application jar and dependencies in /opt/app/lib. Copy webswing.config from your DEV machine to /opt/app/webswing.config. To configure your app setup the classpath like following:

"classPathEntries" : [ "/opt/app/lib/*.jar", "/opt/app/MySwingApp.jar" ]

Run

docker-compose up -d

For more complex docker or kubernetes deployments you can ask for consultation.

#Startup options

#Commandline

Start scripts webswing.bat and webswing.sh are included in Webswing distribution. These scripts may need to be adapted to point to the right Java installation and to configure other custom options.

Starting Webswing with option -h will print out help with list of all possible option.

c:\webswing>java -jar webswing-server.war -h

You can define the following options in start scripts:

Option	Description	Default value
-c <arg>	Configuration file name.	<webswing-server.war path>/webswing.config
-d <arg>	Create new temp folder for every Webswing instance	false
-h <arg>	Local interface address where the web server will listen.	localhost
-j <arg>	Jetty startup configuration file.	./jetty.properties
-kp <arg>	Keystore password.
-ks <arg>	Keystore file location for ssl configuration
-p <arg>	HTTP port where the web server will listen. If 0 HTTP is disable	8080
-s <arg>	HTTPS port where the web server will listen.If 0 HTTP is disabled.	0
-t <arg>	The folder where temp folder will be created for the Webswing server	./tmp
-tc <arg>	Clean the temp folder before Webswing start	true
-tp <arg>	Truststore password
-ts <arg>	Truststore file location for SSL configuration

---

#SSL configuration

You can configure the SSL with embedded jetty (described below) or with Reverse Proxy.

There is a special configuration file for the built-in jetty called jetty.properties. It is used to configure connection options of the server like ports, protocols, SSL certificates and CORS origins (for embedded Webswing ). Command-line options have higher priority than this file. Location of this file can be specified by option -j. You can configure following options in this file:

org.webswing.server.host=localhost

org.webswing.server.http=true
org.webswing.server.http.port=8080

org.webswing.server.https=true
org.webswing.server.https.port=8443
org.webswing.server.https.truststore=ssl/truststore.jks
org.webswing.server.https.truststore.password=OBF:18xp18xr18xt18xp18xr18xt
org.webswing.server.https.keystore=ssl/keystore.jks
org.webswing.server.https.keystore.password=OBF:18xp18xr18xt18xp18xr18xt

To obfuscate the trustore and keystore password Jetty can generate the obfuscated password that can be used in the property file aftwerwards.

Usage:

>java -cp jetty-util-9.4.18.v20190429.jar org.eclipse.jetty.util.security.Password 123123
2019-08-26 12:26:43.711:INFO::main: Logging initialized @140ms to org.eclipse.jetty.util.log.StdErrLog
123123
OBF:18xp18xr18xt18xp18xr18xt
MD5:4297f44b13955235245b2497399d7a93

Afterwards use the obfuscated password in the jetty.properties file. For more details visit Official Jetty Documentation

#Tomcat Deployment

Even though Webswing comes with an embedded Jetty server, it is still possible to deploy it to an external servlet container like Tomcat. Other J2EE servers should work as well, as far as they support Servlet 3.0 spec (but only Tomcat 8 is tested). Previous experience with Tomcat configuration is expected.

To deploy Webswing to Tomcat, follow the following steps:

1. Create a new folder named webswing in Tomcat's home folder and unzip the Webswing distribution to this folder.
2. Make a copy of webswing-server.war from the distribution package in Tomcat's webapps folder.
3. In conf/catalina.properties file add the following properties. ( Or use -D JVM options to specify these properties)

webswing.warLocation=webapps/webswing-server.war
webswing.configFile=webswing/webswing.config
webswing.tempDirBase=webswing/tmp
webswing.rootDir=webswing

Please note that the locations in demo webswing.config are pointing to relative paths, so in order to make the demo applications run in Tomcat you will need to change the paths accordingly.

Tomcat should be executed from it's root folder as .\bin\catalina.bat or the path to the webswing-server.war file in the configuration needs to be adjusted.

In case of issues analyze the logfiles.

#IBM WAS 9.0 Deployment

To deploy Webswing to WAS 9.0, follow these steps:

1. Unzip Webswing distribution to a temporary folder
2. Go to IBM WAS Console http://localhost:9060/ibm/console
3. Navigate in the menu to Applications>New Application>New Enterprise Application
4. Click Choose File (select webswing-server.war from the temporary folder created before)
5. Next>Next>Next>Next>Next
6. Configure Webswing JVM Properties in location: Servers>Server Types> WebSphere application servers>server1>Server Infrastructure, Java and Process Management, Process Definition>Java Virtual Machine>Custom Properties similarly to following:

webswing.warLocation=webapps/webswing-server.war
webswing.configFile=webswing/webswing.config
webswing.tempDirBase=webswing/tmp
webswing.rootDir=webswing

Please note that the locations in demo webswing.config are pointing to relative paths, so in order to make the demo applications run in WAS you will need to change the paths accordingly.

In case of issues analyze the logfiles.