Installation Guide

Webswing is packaged and distributed as a fully working demo package 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 are


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.


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):

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 overriden by setting the following environment variables:

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).

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 server stops.
webswing.sh start Start Webswing as deamon 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.

files.png

  1. webswing-server.war file is the main executable file. This file is a regular java web application archive with embeded 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 "Application setup" section.

  3. user.properties contains the users, passwords and authorization roles. This file is necessary unless you configure your own application security realm in shiro.ini. (more details here)

  4. (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 Server start-up parameters section

Webswing generates following output files:

tmp folder is created for extracting client libraries and temporary files generated by application print or file download functionality. Path for this temporary folder can be changed by defining comman-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 Webswing server is started.

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

webswing.config.backup the webswing.config file content is backed up to this file after this config is changed in administration console. By default last 10 version are kept in this file.