logo
25.1
search
No matching documents found.
Follow us on
Developed by webswing.org

© 2012 - 2025 Webswing Ltd. All Rights Reserved.

list
logo
avatar
expand_more

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.

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 2.7" 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.

files.png

  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: 2.7_jre11

Quick startup:

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

Docker Compose Example:

Create docker-compose.yml file:

version: "3.3"

services:
  webswing:
    image: nimirium/webswing-se:2.7_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