#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 recent major distributions compliant with the LTS Java SE 21, 17, 11 or 8 standards (1.8.0_202-b08 or newer)
• Adoptium, Amazon Corretto, Red Hat JDK, IBM SDK, Oracle JDK

#Hardware requirements

The hardware requirements are application specific. Let's assume the app requires 0.64GB RAM and 0.32CPU. As an example estimation for 100 users we suggest a cluster of 2 servers 32GB RAM and 16 CPU cores each. To handle 50 concurrent users Webswing requires 300MB RAM and 1 CPU core.

Because each application served by Webswing is different, we advocate a data-driven approach rather than relying on rough estimates. We recommend conducting a test with 10 users and closely monitoring the consumption of server resources during typical application usage. By extrapolating these measurements by the required factor, you should obtain more accurate and precise figures.

#Downloading 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 server/webswing-jetty-launcher.jar -j jetty.properties -serveradmin -pfa admin/webswing-admin.properties -adminctx /admin -aw admin/webswing-admin-server.war

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

#Windows Service

#Starting on Linux

#Docker

Dockerfile

You can find an example Dockerfile in the standard Webswing distribution with examples. In case you need to create a Docker image with Webswing you can do so by using&extending it. Extract the distribution.zip file and execute:

docker build -t webswing . docker run -d -p 8080:8080 webswing

This is the Dockerfile you can find in the standard Webswing distribution with examples. It relies on the xheadless which is present only in the distribution with examples.

FROM redhat/ubi9

RUN dnf install -y \
    libXext \
    libXi \
    libXtst \
    libXrender \
    pango \
    gnupg2 \
    socat \
    java-17-openjdk
    
RUN dnf update glibc

# Copy Webswing to the image
COPY . /opt/webswing/

# Configure environment variables
ENV WEBSWING_HOME=/opt/webswing \
    DISPLAY=:99 \
    WEBSWING_OPTS="-h 0.0.0.0 -j /opt/webswing/jetty.properties -serveradmin -pfa /opt/webswing/admin/webswing-admin.properties -adminctx /admin -aw admin/webswing-admin-server.war" \
    WEBSWING_JAVA_OPTS="-Xmx256M -Djava.net.preferIPv4Stack=true -Dwebswing.admin.url=http://localhost:8080/admin"

WORKDIR /opt/webswing

# Create XHeadless service
RUN mkdir -p /etc/service/xheadless && mkdir /tmp/.X11-unix/ && mkdir /opt/webswing/logs/ && \
    echo "#!/bin/sh" > /etc/service/xheadless/run && \
    echo "/opt/webswing/xheadless/xheadless >> /opt/webswing/logs/xheadless.log" > /etc/service/xheadless/run && \
    chmod +x /etc/service/xheadless/run && \
    chmod +x /opt/webswing/xheadless/xheadless

# Create Webswing service
RUN mkdir /etc/service/webswing && \
    echo "#!/bin/sh" > /etc/service/webswing/run && \
    echo "cd $WEBSWING_HOME" > /etc/service/webswing/run && \
    echo "exec $JAVA_HOME/bin/java \$WEBSWING_JAVA_OPTS -jar $WEBSWING_HOME/server/webswing-jetty-launcher.jar \$WEBSWING_OPTS" > /etc/service/webswing/run && \
    chmod +x /etc/service/webswing/run

EXPOSE 8080

# Create startup script which runs XHeadless and Webswing services
RUN echo "#!/bin/sh" > ./start.sh && \
    echo "/etc/service/xheadless/run & /etc/service/webswing/run" > ./start.sh && \
    chmod +x ./start.sh

CMD ./start.sh

Quick startup

Running locally: docker run -d --rm -p 8080:8080 webswing

Running on a server: docker run -d --rm -e WEBSWING_JAVA_OPTS="-Xmx256M -Djava.net.preferIPv4Stack=true -Dwebswing.admin.url=/admin -Dwebswing.server.publicUrl=http://192.168.1.88:8080" -p 8080:8080 webswing

These images are not meant for cluster deployment, please refer to Cluster Deployment section if you need docker images for cluster deployment.

Docker Compose Example:

Create docker-compose.yml file:

version: "3.3"

services:
  webswing:
    image: webswing
    environment:
      - WEBSWING_OPTS=-h 0.0.0.0 -serveradmin -pfa /opt/webswing/admin/webswing-admin.properties -adminctx /admin -aw admin/webswing-admin-server.war -c /opt/app/webswing.config
      - WEBSWING_JAVA_OPTS=-Xmx256M -Djava.net.preferIPv4Stack=true -Dwebswing.admin.url=http://192.168.1.2:8080/admin -Dwebswing.server.publicUrl=http://192.168.1.88:8080
    volumes:
      - /opt/app:/opt/app
    ports:
      - "80:8080"

Environment variable WEBSWING_OPTS specifies startup arguments for the server. You can reference your webswing.config here. Volume syncs container with host, so your config survives the restart of container. Environment variable WEBSWING_JAVA_OPTS is for specifying all the system properties that needs to be changed. The most important one in docker context is webswing.admin.url that is mapped in webswing.config. This URL link is behind the Manage button in the application selector screen. Please note that admin console can run in a different container/host/server, or not run if it is not needed. In the docker-compose example file we expect that the server has IP address 192.168.1.2. 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

#Startup options

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:

#Startup properties

You can define the following properties in webswing.properties file:

Property	Description	Default value
webswing.connection.secret	Secret string for securing user sessions and websocket connections used by Webswing server. Should be a 128 characters long string. If you are using admin console, use the same secret in webswing-admin.properties.
webswing.connection.secret.file	Alternative way to specify secret string in a file.
webswing.logsDir	Directory where Webswing server log files should be stored. This needs to be set as java property -Dwebswing.logsDir when starting the process.	logs/
webswing.server.websocketUrl	Provide this property only if you are going to deploy webswing-server.war on your own server, without using embedded Jetty. This property should contain the websocket URL of this Webswing server, e.g. ws://localhost:8080.
webswing.sessionPoolDumpDir	Directory where thread dumps generated by session pool should be stored.	.

#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 and SSL context. 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

In case you are not using embedded Jetty, please follow the documentation for setting up SSL for your Servlet container. Additionaly you will need to setup SSL truststore for websocket connection from app sessions (in webswing.properties file), session pool (in webswing-sessionpool.properties file) and admin console (in webswing-admin.properties file).

1. Set the webswing.server.websocketUrl to use wss Url schema.
2. Add truststore containing the CA that signed the SSL certificate. This truststore will only be used for context of websocket connection to Webswing server.:

#Custom ssl context configuration for websocket connection to Webswing server
webswing.server.websocket.truststore.type = PKCS12
webswing.server.websocket.truststore = ssl/truststore.p12
webswing.server.websocket.truststore.password = OBF:18xp18xr18xt18xp18xr18xt

3. If the websocketUrl is not the same as public domain name the SSL certificate is issued for, add the following line: webswing.server.websocket.hostnameVerifier.disabled = true
4. If the websocket connection should connect through a forward proxy, add the following line: webswing.server.websocket.proxyUri = http://myproxy:8080

#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 and JSR-356 Websocket spec (Tomcat 8 and 10 is tested). Previous experience with Tomcat configuration is expected.

To deploy Webswing to Tomcat, follow the following steps:

#IBM WAS 9.0 Deployment

To deploy Webswing to WAS 9.0, follow these steps:

1. Unzip Webswing distribution to a temporary folder
2. In webswing.properties set property webswing.server.websocketUrl to ws://localhost:<port>, port should be the same as application server port
3. Go to IBM WAS Console http://localhost:9060/ibm/console
4. Navigate in the menu to Applications>New Application>New Enterprise Application
5. Click Choose File (select webswing-server.war from the temporary folder created before)
6. Next>Next>Next>Next>Next
7. 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.