#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

• Oracle Java 1.8.0_25+

---

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

• 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

Supported tags: 2.6.1_jre11, 2.6.1_jre8, 2.6_jre11, 2.6_jre8

Quick startup:

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

Docker Compose Example:

Create docker-compose.yml file:

version: "3.3"

services:
  webswing:
    image: nimirium/webswing-se:2.6_jre11
    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