Summary: The following sections provide a brief explanation of the installation/configuration process for Apache Tomcat when you want to deploy a WAR file. This documentation is not intended to replace the Apache Tomcat official documentation and is simply for reference only. Note that CAST also provides ZIP files based on Spring Boot for deploying CAST dashboards without the need for Apache Tomcat.

JDK / JRE on Microsoft Windows

Apache Tomcat requires a Java JRE or JDK. If you are installing Apache Tomcat as a Windows Service, then a JRE is included and will be used. If you are installing Apache Tomcat in "standalone mode" on Windows, then a Java JRE or JDK is required:

CATALINA_HOME environment variable

A CATALINA_HOME environment variable is required regardless of the operating system used to host Apache Tomcat.

Microsoft Windows

Create a SYSTEM environment variable called CATALINA_HOME. This should be set to the directory where Tomcat has been installed:

Click to enlarge

Linux

If installing Apache Tomcat from a repository such as apt, then the CATALINA_HOME environment variable will be automatically set.

If you are installing Apache Tomcat from a downloaded archive file, you will need to set the CATALINA_HOME variable manually as follows:

To make the variable available to all users on the system:

vim /etc/bashrc

To make it available to the current user:

vim ~/.bashrc

Then add the following line:

export CATALINA_HOME=/path/to/tomcat


Apache Tomcat performance considerations

Memory configuration

It may be necessary to modify the default memory settings for Apache Tomcat to improve the performance of your deployed dashboards. CAST recommends the following formula for determining the maximum memory allocation to configure on Apache Tomcat:

Number of dashboards x Y MB, where Y should be at least 512 MB.

In some circumstances, whilst using a CAST dashboard, you may receive Low Memory/Recovered Memory/Out of Memory errors or exceptions, for example:

[WARNING]: [MEM] Low Memory: 24052448
[WARNING]: [MEM] Recovered Memory: 18348800

These errors and exceptions are displayed by the Java Virtual Machine (JVM) and they indicate that the Java Garbage Collector is in operation. As a result, you may see a slow down in performance. You can ignore these errors, however, if they persist, it is possible to modify the JVM memory configuration settings on the machine hosting the Apache Tomcat server to resolve the problem.

The procedure for modifying the JVM memory settings is dependent on how you have installed Tomcat - either as a service or standalone (launched via the command line).

Installed as a Windows Service

If you have installed Apache Tomcat as a service, the process "Tomcat7.exe" or "Tomcat8.exe" will be visible in the Processes tab in Windows Task Manager. To modify the JVM memory configuration:

Installed as a standalone program

If Apache Tomcat is installed as a standalone program and is launched from the command line, CAST recommends using a wrapper script file with the following parameter line:

set CATALINA_OPTS=-Xms512m -Xmx512m

This will set the JVM memory configuration settings as follows: - Initial memory pool = 512MB, - Maximum memory pool = 512MB (these are the minimum values that CAST recommends - you should increase these values until your low memory/out of memory exceptions have been resolved). An example wrapper script for Microsoft Windows to launch Apache Tomcat with the above configuration is shown below (modify to suit your own environment):

@echo off
if "%OS%" == "Windows_NT" setlocal
set JAVA_HOME=C:\Java\jdk1.5.0_06
set PATH=C:\Java\jdk1.5.0_06\bin;%PATH%
set CATALINA_HOME=C:\apache-tomcat-5.5.17
set CATALINA_OPTS=-Xms512m -Xmx512m
rem launch Tomcat standard startup.bat
call startup.bat
:end

Nightly restarts

CAST highly recommends that the application server is configured to restart automatically on a regular basis (every night for example, or when not in use). This will clear any potential memory issues.

Note that when restarting the application server, the data cache used for the CAST dashboards will also be cleared, therefore the first user to connect may have degraded performance until this cache is repopulated.