====== Webswing GLI ======

Webswing is a technology that allows java programs to run in a browser.\\
Greenstone 3.11 and later comes with webswing enabled, so that GLI can be run in a browser, allowing remote users the ability to build and edit collections on the server without having to install Greenstone (and Remote GLI).\\
To get started using webswing GLI, see tutorial [[https://files.greenstone.org/tutorial/gs3-current/en/webswing_gli.htm| Using Webswing GLI]]

It is provided as an extension, in greenstone3/ext/webswing. You don't need to compile it up, Greenstone3 ships with a ready-to-go webswing JAR/WAR file.

The webswing framework requires a graphical environment. If you are on a standard desktop, then it will work out of the box.
However, if you are on a headless Linux environment, then you will need to install:
  * xvfb  (x-virtual frame buffer) - for example, ''sudo apt install xvfb''
You may also need the following:
  * libxext6
  * libxi6
  * libxtst6
  * libxrender1

To start Greenstone when you are using webswing, please use the new scripts:
  * ant-start-with-exts.sh 
  * ant-stop-with-exts.sh
  * ant-restart-with-exts.sh 

These will make sure the right environment is set up for Tomcat.

==== When Tomcat is behind an Apache server ====

If you Tomcat is running behind an Apache webserver, there are some extra steps to get it running in this situation.

  * Apache needs to have the proxy_wstunnel module enabled: 
     * (sudo) apachectl -M   - to list modules
     * (sudo) a2enmod proxy_wstunnel    - to enable the module

See [[https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html]]

You also need to edit the apache configuration file for your VirtualHost. This file might be in eg /etc/apache2/sites-available/000-default-le-ssl.conf, or /etc/httpd/conf.d/yourcustomname.conf.

Assuming your tomcat is running on port 8383:

If your apache is 2.4.47 or later:

<code>
ProxyPass "/webswing-server/" "http://localhost:8383/webswing-server/" upgrade=websocket
</code>

If your apache is older than 2.4.47, try the following:
<code>
    RewriteEngine on

    RewriteCond %{HTTP:Upgrade} =websocket
    RewriteRule /(.*) ws://localhost:8383/$1 [P,L]

    RewriteCond %{HTTP:Upgrade} !=websocket
    RewriteRule /(.*) http://localhost:8383/$1 [P,L]

</code>

Note, this doesn't work if you have two greenstone installs running at the same time, on different ports.




==== Configuration ====

There is a config file web/ext/webswing/etc/webswing.config.in. You can edit that. When you run an ant restart, webswing.config will be generated from this .in file.

Some useful settings in this file:
  * uploadMaxSize - the maximum file size allowed to be uploaded (FileChooser) in MB. Set to 0 for unlimited size. Note, if the size is less than a file you are trying to upload to a collection, it will silently fail and give you no reason why.
  * 

==== Debugging ====

  * webswing log goes to packages/tomcat/bin/logs/webswing.log. GLI System.err goes there.
  * For GLI debugging - add -debug to the args for GathererProg in web/ext/websing/etc/webswing.config.in. Restart tomcat. A GLI log file will go to gli/webswing-users/<username>/debug<date>.txt. Note, this folder is also where the GLI config file is stored for the user - configWebswing.xml. GLI DebugStream.println goes here.


====Deactivating Webswing ====

Webswing is used for web-based GLI, Phind and Collage classifiers. If you don't need any of these things you can deactivate webswing by running:

<code>
cd <PATH-TO_GS3-INSTALL>/ext
./DEACTIVATE.sh webswing
</code>

It can be re-activated by running ''./ACTIVATE.sh webswing'' in the same folder.