- work in progress -
Before starting iteraplan you have to make a few configuration adjustments to your Tomcat application server. This is only needed when using the Installer variant for installation. The Docker variant comes preconfigured with the suitable settings.
Tomcat Host Configuration
In the file
$TOMCAT_HOME/conf/server.xml, the name of the host and the base location of the web applications is configured in the
<HOST> element. It is best to leave this configuration unchanged at Tomcat default values. Most important is that the attribute unpackWARs is set to true:
Tomcat Connector Configuration
iteraplan'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, find all active occurrences of the <Connector> tag and add the attribute
URIEncoding="UTF-8" to all of these tags. For instance, the HTTP connector might look as follows, where the last attribute has been added:
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 the iteraplan support in order to find a solution.
Limit Maximum Number of Request-processing Threads
If the Tomcat on which iteraplan is deployed is not expected to run under heavy load and/or iteraplan is the only application deployed on it, we recommend you to limit the number of Tomcat threads that process requests to 20. In order to do this, the
$TOMCAT_HOME/conf/server.xml has to be modified.
First, you have to define an
Executor with the name
iteraplanThreadPool within the Service Catalina (after the line
<Service name="Catalina">), if it does not already exist. It should look like this:
Then, you have to change the 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.
Please note that, while the settings for these connectors may vary depending on your personal system's configuration, the
executor attribute has to 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 iteraplan. Such a situation may occur when there are more threads writing concurrently to the database than database connections are available. The standard configuration for iteraplan's database connection pool is 21, to ensure that there is always at least one more database connection available and to avoid this problem.
If, for some reason, 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 the
maxThreads attribute to a more appropriate value. It is strongly recommended though, that the maximum number of database connections is updated accordingly, such 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 find out which number of connections is acceptable for 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 are transmitted. If you have any problems with the header size, add a
maxHttpHeaderSize = "65536" to increase enlarge from the default maximum of 8K to 64K.
Information to set up Tomcat for SSL can be found in the official Tomcat documentation:
- Tomcat 8: https://tomcat.apache.org/tomcat-8.0-doc/ssl-howto.html
- 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 iteraplan for SSL can be found here: Configuration Options and Notes
To speed up the initial load of the iteraplan client (amongst other operations) we recommend to enable 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
Here are examples how the different Tomcat Connectors could be configured, based on the instructions above.
In the default configuration the caching of Tomcat 8 is set to "false". When starting the service some warnings appear: "insufficient free space available after evicting expired cache entries". Add the following line in the file $TOMCAT_HOME/conf/server.xml. After this change the warnings disappear.
In the default configuration, Apache Tomcat uses only up to 64 MB of memory for all the applications installed on it. You have to increase this value to make sure that iteraplan can run reliably. If you 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 some 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 of these is available, you can launch the tray icon by running these commands on the command line (adjust paths to your machine and Tomcat version):
In this properties dialog, you can adjust the memory options on the Java tab. We recommend to set at least 2048 MB for the 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:
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 that you defined in setenv.bat. Instead, you need to use the configuration utility as shown above.
Tomcat in headless mode for terminal-only Unix/Linux systems
In order to run iteraplan on a headless (terminal only) Unix/Linux system, you need to add the following option to the CATALINA_OPTS: