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 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:
<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true"> ... possible further settings ... </Host>
Tomcat connector 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:
<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:
<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.
<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
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
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.
<Connector ... maxHttpHeaderSize="65536" ... />
Information on setting up Tomcat for SSL can be found in the official Tomcat documentation:
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.
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
Example connector configurations
Below are examples of different Tomcat connectors and their configurations, based on the instructions above.
<Connector executor="luyThreadPool" port="8009" protocol="AJP/1.3" redirectPort="8443" packetSize="65536" URIEncoding="UTF-8" />
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.
<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):
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:
(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:
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.
... CATALINA_OPTS="$CATALINA_OPTS -Dchrome_binary=/path/to/your/google-chrome" ..