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:
- Download the required JRE or JDK
- Install the JRE or JDK
- Create a SYSTEM environment variable named JAVA_HOME. This should point to the folder in which the JRE or JDK has been installed (i.e. C:\Java\jre)
- Update the PATH system environment variable by adding %JAVA_HOME%\bin at the beginning of the list of paths
- Open a command prompt (Start -> Run -> cmd)
- Type "java -version" and verify that the correct java version is installed. You should see something like this:
CATALINA_HOME environment variable
A CATALINA_HOME environment variable is required regardless of the operating system used to host Apache Tomcat.
Create a SYSTEM environment variable called CATALINA_HOME. This should be set to the directory where Tomcat has been installed:
Click to enlarge
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:
To make it available to the current user:
Then add the following line:
Apache Tomcat performance considerations
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:
In some circumstances, whilst using a CAST dashboard, you may receive Low Memory/Recovered Memory/Out of Memory errors or exceptions, for example:
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:
- Stop the Apache Tomcat service
- Execute the Tomcat7w.exe or Tomcat8w.exe file located at C:\Program Files\Apache Software Foundation\bin or your equivalent installation location
- Select the Java tab as shown below:
- Alter (or add) 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).
- Click Apply and then OK to confirm the modification to the JVM memory settings
- Restart Tomcat to use the new settings
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:
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):
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.