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 Java SE 11 or 8 standards (1.8.0_202-b08 or newer)
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 webswing-server.war -j jetty.properties
Note: Make sure
java
is pointing to a supported java version by runningjava -version
from your command line.
If you need Admin Console then use webswing&admin.bat
.
Windows Service
Starting on Linux
Docker
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:
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 . |
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
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 (but only Tomcat 8 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:
- Unzip Webswing distribution to a temporary folder
- In
webswing.properties
set propertywebswing.server.websocketUrl
tows://localhost:<port>
, port should be the same as application server port - Go to IBM WAS Console http://localhost:9060/ibm/console
- Navigate in the menu to
Applications>New Application>New Enterprise Application
- Click Choose File (select
webswing-server.war
from the temporary folder created before) -
Next>Next>Next>Next>Next
- 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.