Tomcat configuration

Before starting LUY there are a few configuration adjustments necessary on your Tomcat application server. This is only needed when using the installer variant for installation. The Docker variant is preconfigured with all suitable settings.

Tomcat JDBC connector

Copy the driver file (a .jar file) into the library directory of your Apache Tomcat installation. The directory is usually one of the following, with TOMCAT_HOME referring to the installation directory of Apache Tomcat:

TOMCAT_HOME/lib
TOMCAT_HOME/common/lib
TOMCAT_HOME/server/lib

Tomcat host configuration

In the file $TOMCAT_HOME/conf/server.xml, the name of the host and the base location of the web applications are configured in the <HOST> element. It is best to leave this configuration unchanged at Tomcat default values. It is important that the attribute unpackWARs is set to true:

CODE

      <Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="true">

		... possible further settings ...
		
      </Host>

Tomcat connector configuration

Encoding configuration

LUY's pages are consistently encoded in UTF-8, as to allow for representation of non-latin characters. It is necessary to adjust Tomcat's configuration so that it uses UTF-8 for interpreting incoming requests as well. Failure to adjust that setting may result in corrupted data when non-English characters (such as German umlauts) are involved.
In the file $TOMCAT_HOME/conf/server.xml, you find all active occurrences of the <Connector>-tag. Add the attribute URIEncoding="UTF-8" to all of these tags. For instance, the HTTP connector might look as follows with the last attribute added:

CODE

<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" URIEncoding="UTF-8" />

Typically, there are between one and three active connectors configured in Tomcat. Be sure to add the attribute to all of them. Please be aware that this option applies to all applications which are deployed on your Tomcat. Under rare circumstances, this setting might break character encoding of non-English characters in other applications on that Tomcat instance. Should you experience such problems, please contact LUY support in order to find a solution.

Limit maximum number of request-processing threads

If the Tomcat on which LUY is deployed is not expected to run under heavy load and/or LUY is the only application deployed on it, we recommend to limit the number of Tomcat threads that process requests to 20. In order to do this, the $TOMCAT_HOME/conf/server.xml must be modified.

First, you have to define an Executor with the name luyThreadPool within the service Catalina (after the line <Service name="Catalina">) if it does not already exist. It should look like this:

CODE

<Executor name="luyThreadPool "
          namePrefix="catalina-exec-"
          maxThreads="20"
          minSpareThreads="4" />

Then, you have to change connectors to use the given thread pool. Normally, these are any or all of the connectors for the AJP (8009), HTTP (8080) and HTTPS (8443) protocols.

CODE

<Connector executor="luyThreadPool"
           ...
           other attributes
           ... />

Please note that the settings for these connectors may vary depending on your personal system's configuration, yet the executor attribute must be set and the connectors themselves must not specify any of the attributes maxThreads or minSpareThreads to avoid conflicts.

This causes all requests to be handled by Tomcat with a maximum of 20 threads. The purpose of this is to avoid a possible deadlock in one of the database access libraries used by LUY. Such a situation may occur when there are more threads concurrently writing to the database than database connections are available. The standard configuration for LUY's database connection pool is 21 to ensure that there is always at least one more database connection available and thereby avoid this problem.

If your Tomcat needs to be able to handle requests on these ports in more threads, we still recommend that you configure it as described above but change the value of maxThreads to a more suitable value. It is strongly recommended, though, that the maximum number of database connections is updated so that it is always higher than the maximum number of threads. This can be done by changing the value of the properties database.pool.maxIdle and database.pool.maxActive in luy/WEB-INF/classes/luy-db.properties.

Please contact your database admin to identify the number of connections appropriate to your database.

HTTP header size

The Tomcat connector attribute maxHttpHeaderSize defines the maximum size of the request and response HTTP header, specified in bytes. If not specified, this attribute is set to 8192 (8 KB). In some cases, this may be insufficient, particularly when larger data on the HTTP header is transmitted. If you have any problems with the header size, add a maxHttpHeaderSize = "65536" to increase the default maximum of 8K to 64K.

CODE

<Connector ...
           maxHttpHeaderSize="65536"
           ... />

SSL

Information on setting up Tomcat for SSL can be found in the official Tomcat documentation:

Tomcat 9: https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html

An example configuration for a Tomcat SSL connector can be found below.

More information about setting up LUY for SSL can be found here: configuration options and notes.

Enable compression

In order to speed up the initial load of the LUY client (amongst other operations) we recommend enabling compression in the Tomcat connector. This is not mandatory, but generally a good idea.

If you want to enable compression, add the following two settings to the connector entry in the Tomcat server.xml file:

CODE

compression="on"
compressableMimeType="application/json,text/html,text/xml, 
text/plain,text/css,text/javascript,application/javascript"

Example connector configurations

Below are examples of different Tomcat connectors and their configurations, based on the instructions above.

AJP connector:

CODE

<Connector executor="luyThreadPool"
           port="8009"
           protocol="AJP/1.3"
           redirectPort="8443"
           packetSize="65536"
           URIEncoding="UTF-8" />

HTTP connector:

CODE

<Connector executor="luyThreadPool"
           port="8080"
           protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443"
           maxHttpHeaderSize="65536"
           URIEncoding="UTF-8"
           compression="on"
           compressableMimeType="application/json,text/html,text/xml, text/plain,text/css,text/javascript,application/javascript"
/>

HTTPS connector:

CODE

<Connector executor="luyThreadPool"
           protocol="HTTP/1.1"
           port="8443"
           acceptCount="100"
           disableUploadTimeout="true"
           maxHttpHeaderSize="65536"
           URIEncoding="UTF-8"
           compression="on"
           compressableMimeType="application/json,text/html,text/xml, text/plain,text/css,text/javascript,application/javascript"
           enableLookups="false"
           scheme="https"
           secure="true"
           SSLEnabled="true"
           clientAuth="false"
           sslProtocol="TLS"
           keystoreFile="./conf/.keystore"
           keystorePass="luy" />

Memory settings

In the default configuration, the caching of Tomcat 9 is set to "false". When starting the service, these warnings may appear: "insufficient free space available after evicting expired cache entries". Add the following line in the file $TOMCAT_HOME/conf/context.xml. After this change, the warnings will disappear.

CODE

 <Resources cachingAllowed="true" cacheMaxSize="100000" />

In the default configuration, Apache Tomcat uses only up to 64 MB of memory for all applications installed on it. You have to increase this value to make sure that LUY can run reliably. If you have installed Tomcat as a Windows service, the Tomcat service properties tool allows you to adjust these memory settings. On Unix systems and for the standalone Windows version (unpacked zip file), you need to adjust environment variables, as described below.

You can open the service management tool for Tomcat from the tray icon (right-click and configure) or from the start menu entry. If neither is available, you can launch the tray icon by running these commands on the command line (adjust paths to your machine and Tomcat version):

CODE

cd \Program Files\Apache\Tomcat X.Y.ZZ\bin
tomcat7w.exe //MS//

In the properties dialog, you can adjust memory options on the Java tab. We recommend setting at least 2048 MB for maximum memory pool.

If you are running Tomcat on a Unix system or with Windows batch scripts, you need to set the environment variable CATALINA_OPTS. Create a file setenv.sh (or setenv.bat on Windows) in the Tomcat bin directory and enter the following line:

CODE

(Unix): export CATALINA_OPTS="-Xmx2048m -Djava.awt.headless=true"
(Windows): set CATALINA_OPTS=-Xmx2048m

Please note that other applications running on the same tomcat are also affected by this global option.

This approach does not work if Tomcat is run as a Windows service! The Windows service will ignore the values defined in setenv.bat. Instead, you need to use the configuration utility shown above.

Tomcat in headless mode for terminal-only Unix/Linux systems

In order to run LUY on a headless (terminal only) Unix/Linux system, you need to add the following option to the CATALINA_OPTS:

CODE

-Djava.awt.headless=true

Configure Chrome or Chromium

Chrome or Chromium must be installed on the LUY server to enable the shared visualization feature. Set the system property chrome_binary in the Tomcat startup configuration, e.g.

CODE

...
CATALINA_OPTS="$CATALINA_OPTS -Dchrome_binary=/path/to/your/google-chrome"
..