Tomcat update

Caution

The upgrade procedure described below is valid for Tomcat versions:

• 9.0.115 and later

By default, OpenKM is installed with a specific Tomcat version. But every few weeks, a new version is released, and you may want your installation to be up to date. In this case, you should open a ticket on the OpenKM support website to ensure this new version has been packaged by the OpenKM Team. Once you have verified that the new version is available and have downloaded it, you must follow the steps described in this section of the documentation.

Caution

Before updating Tomcat, we recommend upgrading to the latest OpenKM version and ensuring you have a recent working backup.

Note

Although you can use a pristine Tomcat, we always recommend using those provided by the OpenKM team because they have additional files and default configurations that work best with OpenKM.

Quick method

The easiest method to update your Tomcat instance is to follow these steps:

• Stop the current Tomcat / OpenKM process.
• Download the latest Tomcat provided by the support team.
• Remove the contents of the TOMCAT_HOME/lib folder and replace them with the downloaded content.
• Start Tomcat / OpenKM again.

Once the process has finished, you can verify the new version:

$ cd TOMCAT_HOME
$ ./bin/catalina.sh version

Linux

Preliminaries

• Check the openkm.properties file to see whether you have a special repository path location (more information at Change repository home).

Tomcat replacement

• Stop the current Tomcat
• Unzip the new Tomcat
• Copy these files and folders from the old Tomcat to the new one:

Caution

Remember when copying and moving data to check the security applied to the destination. Sometimes, when you move data, the applied security might change, which causes issues in the OpenKM startup process.

You can set them recursively:

$ sudo chown openkm:openkm tomcat-9.0.115 -R

Name	Type	Comments
tomcat-XXX/bin/setenv.sh	File	Optional. Only required if you have modified this file.
tomcat-XXX/openkm.properties	File	OpenKM configuration file. If there’s a mistake in copying this file, it might damage the repository. Please check that the file has been copied correctly to the destination.
tomcat-XXX/openkm.xml	File	OpenKM security configuration file. This file might not exist. You can find this file only in a special installation.
tomcat-XXX/logback.xml	File	OpenKM log configuration file. It might not exist.
tomcat-XXX/repository	Folder	The folder where documents are stored. If there’s a mistake in copying this folder, it might damage the repository. Please check that the folder has been copied correctly to the destination.
tomcat-XXX/plugins	Folder	Directory with OpenKM plugins. It might be empty. It only contains files if the OpenKM instance has customizations.
tomcat-XXX/webapps	Folder	OpenKM deployed application.
tomcat-XXX/jbpm-console.properties	File	jBPM engine configuration file. This file might not exist. This file exists only if the jBPM engine has been installed.

• Update your Tomcat service configuration:
  • Change the Tomcat path in /etc/init.d/openkm
• Start OpenKM
• Go to Administration > Configuration parameters 
• Filter in the top right corner by the word “tomcat”
• Replace the old Tomcat path used in configuration parameters with the new path.
• Restart OpenKM service.
• Do a quick test.

Note

Suggested quick test:

• Browse the repository.
• Download an existing file.
• Upload a new file and try to download it.

Danger

Remember to update the backup script because the location of the Tomcat directory will change. On Linux, you can check it by running (as root):

$ crontab -l

This way, you can see the location of the backup script.

Preserving the old Tomcat is a good idea, but keep in mind that the backup script usually backs up the /home/openkm directory, so move it to another location.

Windows

Preliminaries

• From Services, check the user running OpenKM. Usually the user should be “Local Services”, but sometimes a standard user is used. Remember to choose the right user when registering the OpenKM service again.
• Check the openkm.properties file to see whether you have a special repository path location (more information at Change repository home).

Tomcat replacement

• Stop OpenKM from services.
• Delete OpenKM from services.

Note

Two options to delete OpenKM from services:

First option:

• Open a terminal as an Administrator user.
• Go to the tomcat-XXX/bin folder.
• Execute the following command:

$:> service.bat remove

Second option:

• Open a terminal as an Administrator user.
• Execute the following command:

$:> sc delete OpenKM

• Unzip the new Tomcat.
• Copy these files and folders from the old Tomcat to the new one:

Caution

Remember when copying and moving data to check the security applied to the destination. Sometimes, when you move data, the applied security might change, which causes issues in the OpenKM startup process.

Name	Type	Comments
tomcat-XXX\bin\setenv.bat	File	Optional. Only required if you have modified this file.
tomcat-XXX\openkm.properties	File	OpenKM configuration file. If there’s a mistake in copying this file, it might damage the repository. Please check that the file has been copied correctly to the destination.
tomcat-XXX\openkm.xml	File	OpenKM security configuration file. This file might not exist. You can find this file only in a special installation.
tomcat-XXX\logback.xml	File	OpenKM log configuration file. It might not exist.
tomcat-XXX\repository	Folder	The folder where documents are stored. If there’s a mistake in copying this folder, it might damage the repository. Please check that the folder has been copied correctly to the destination.
tomcat-XXX\plugins	Folder	Directory with OpenKM plugins. It might be empty. It only contains files if the OpenKM instance has customizations.
tomcat-XXX\extras	Folder	Third-party applications used by OpenKM
tomcat-XXX\webapps	Folder	OpenKM deployed application.
tomcat-XXX\jbpm-console.properties	File	jBPM engine configuration file. This file might not exist. It exists only if the jBPM engine has been installed.

• Configure OpenKM as a service

Note

• Open a terminal as an Administrator user.
• Go to the tomcat-XXX/bin folder.
• Execute the following command:

$:> service.bat install

• Execute the following command:

$:> openkm //US//OpenKM ++JvmOptions="-XX:+UseG1GC"
$:> openkm //US//OpenKM ++JvmOptions="-XX:+UseStringDeduplication"
$:> openkm //US//OpenKM ++JvmOptions="-XX:+HeapDumpOnOutOfMemoryError"
$:> openkm //US//OpenKM ++JvmOptions="-XX:HeapDumpPath=$CATALINA_HOME"
$:> openkm //US//OpenKM ++JvmOptions="-Djava.net.preferIPv4Stack=true"
$:> openkm //US//OpenKM ++JvmOptions="-Dmail.mime.ignoreunknownencoding=true"
$:> openkm //US//OpenKM ++JvmOptions="-Dfile.encoding=utf-8"
$:> openkm //US//OpenKM ++JvmOptions="-Dsun.jnu.encoding=UTF-8"
$:> openkm //US//OpenKM ++JvmOptions="-Djava.awt.headless=true"
$:> openkm //US//OpenKM ++JvmOptions="-Dsun.java2d.cmm=sun.java2d.cmm.kcms.KcmsServiceProvider"

• Start the OpenKM service
• Go to Administration > Configuration parameters 
• Filter in the top right corner by the word “tomcat”.
• Replace the old Tomcat path used in configuration parameters with the new path.
• Restart OpenKM service.
• Do a quick test.

Note

Suggested quick test:

• Browse the repository.
• Download an existing file.
• Upload a new file and try to download it.