- work in progress -

Skip to end of metadata
Go to start of metadata

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:

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

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

Tomcat Connector Configuration

Encoding 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:

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

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

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.

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

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 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 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 database.pool.maxIdle and database.pool.maxActive in iteraplan/WEB-INF/classes/iteraplan-db.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.

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

SSL

Information to set 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 iteraplan for SSL can be found here: Configuration Options and Notes

Enable Compression

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 server.xml file:

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

Example Connector configurations

Here are examples how the different Tomcat Connectors could be configured, based on the instructions above.

AJP connector:

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

HTTP connector:

<Connector executor="iteraplanThreadPool"
           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:

<Connector executor="iteraplanThreadPool"
           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="iteraplan" />

Memory Settings

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.

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

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):

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

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:

(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 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:

-Djava.awt.headless=true



  • No labels