Tomcat update
The upgrade procedure described below is valid for Tomcat versions:
- 8.5.57 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 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.
Before updating Tomcat, we recommend upgrading to the latest OpenKM version and ensuring you have a recent working backup.
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 in the openkm.properties file 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:
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-8.5.47 -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 copying this file, it might damage the repository. Please check that the file has been correctly copied 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 copying this folder, it might damage the repository. Please check that the folder has been correctly copied 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.
Suggested quick test:
- Browse the repository.
- Download an existing file.
- Upload a new file and try to download it.
Remember to update the backup script because the location of the Tomcat directory will change. In case of Linux, you can check it by doing (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.
If you want a more recent branch, you can try Tomcat 9.0, but keep in mind that this new branch has not been fully tested and is not supported by the OpenKM team.
Windows
Preliminaries
- From the services, check the user executing 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 whether you have a special repository path location (more information at Change repository home).
Tomcat replacement
- Stop OpenKM from services.
- Delete OpenKM from services.
Two options to delete OpenKM from services:
First option:
- Open a terminal with an Administrator user.
- Go to tomcat-XXX/bin folder.
- Execute the next command:
$:> service.bat remove
Second option:
- Open a terminal with an Administrator user.
- Execute the next command:
$:> sc delete OpenKM
- Unzip the new Tomcat.
- Copy these files and folders from the old Tomcat to the new one:
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 copying this file, it might damage the repository. Please check that the file has been correctly copied 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. Might not exist. |
|
tomcat-XXX\repository |
Folder |
The folder where documents are stored. If there's a mistake copying this folder, it might damage the repository. Please check that the folder has been correctly copied 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. This file exists only if the jBPM engine has been installed.
|
- Configure OpenKM as a service
- Open a terminal with an Administrator user.
- Go to tomcat-XXX/bin folder.
- Execute the next command:
$:> service.bat install
- Execute the next 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.
Suggested quick test:
- Browse the repository.
- Download an existing file.
- Upload a new file and try to download it.
