How to move to another server

Caution

Although the system should not be affected, before performing this kind of action, we recommend creating a backup. Refer to the Backup and restore section.

Linux

Tip

In the following documentation, we will refer to the Installing on Ubuntu and Debian in some sections because they are the same actions.

Preliminaries

• Ensure you have enough disk space on the new server.
• Check if you have enough CPU power and RAM on the new server.
• Create the user who is the owner of the OpenKM files ( $TOMCAT_HOME folder). This user is usually named “openkm” ( more info at Installing on Ubuntu and Debian), but a different user may have been chosen during installation.
• Update the OS.

Stop OpenKM service

It is important that, while moving the data between the two servers, no changes are made on the old server. That’s why it is a good practice to stop OpenKM.

Caution

If you do not want to stop the OpenKM service, set OpenKM as read-only with a configuration parameter named “system.readonly”.

Backup the database

The database connection is configured in the “openkm.properties” file (in the $TOMCAT_HOME folder). In the following sample the user is named “openkm” with password “openkm” and the connection URL is “jdbc:mariadb://localhost:3306/okmdb?autoReconnect=true&useUnicode=true&characterEncoding=UTF8&nullNamePatternMatchesAll=true”:

# Database connection
spring.datasource.driver-class-name=org.mariadb.jdbc.Driver
spring.datasource.url=jdbc:mariadb://localhost:3306/okmdb?autoReconnect=true&useUnicode=true&characterEncoding=UTF8&nullNamePatternMatchesAll=true
spring.datasource.username=openkm
spring.datasource.password=openkm

The command below explains how to back up the MySQL and MariaDB database. The database is usually named “okmdb”:

$ mysqldump -h localhost -u openkm -popenkm okmdb > okmdb.sql

Restore the database

• Install the same database engine on the new server.
• Create the database user with the same credentials ( more info at Installing on Ubuntu and Debian ).
• Copy the okmdb.sql file to the new server.
• Restore the backup.

The sample below explains how to restore a MySQL or MariaDB database. Again, the database is usually named “okmdb”:

$ mysql -h localhost -u openkm -popenkm okmdb < okmdb.sql

Copy binary files

Caution

Take a look at the file OpenKM.cfg. The whole repository is usually in the TOMCAT_HOME folder, but depending on your configuration it may be configured in another location. This repository folder should also be copied.

Take a look at the parameters in Change repository home.

• Copy the TOMCAT_HOME folder to the new server. We suggest keeping the same original folder path on the destination (otherwise you would need to perform extra configuration steps).
• Set the owner and permissions for the TOMCAT_HOME folder on the new server (usually the user named openkm).

The sample below shows how to copy it (from the old server to the new server):

$ rsync -avh --progress --stats /home/openkm/tomcat-8.5.69 root@newServer:/home/openkm/tomcat-9.0.79

The sample below shows how to set the owner (you need to execute as root):

$ chown openkm:openkm -Rf /home/openkm/tomcat-8.5.69

Configure service on the new server

• Copy the file /etc/init.d/openkm to the same location on the new server and register it as a service. ( more info at Installing on Ubuntu and Debian ).

Install third-party tools

Caution

In OpenKM Administration > Configuration parameters you will find information about most applications required. Some of them are in the $TOMCAT_HOME/bin folder, so these were already copied in previous steps as part of the TOMCAT_HOME folder.

The minimum required packages are ( more info at Installing on Ubuntu and Debian):

• ImageMagick
• Ghostscript
• LibreOffice
• Tesseract OCR engine (remember the language packs required in your environment)

Start OpenKM service

Caution

Until the license is moved to the new server, you will only be able to access the administration user interface.

• If the new server has less RAM than the old server, check the $TOMCAT_HOME/bin/setenv.sh file and adjust it accordingly.
• Check the openkm.log file for the startup process and look for possible errors.

Additional steps

• If the new server has a different number of cores, you need to check the value of the configuration parameters named “text.extraction.threads” and “text.extraction.batch”.
• Open the administration interface at http://localhost:8080/openkm/management/ and run a repository checker (this action may take a long time to complete).

Moving license

Danger

Coordinate with the OpenKM team to move the license from the old server to the new one.

Final checks

• Check the preview of different document types (PDF, Microsoft Office).
• Check the thumbnails of different document types (PDF, Microsoft Office).
• Create a folder.
• Upload a new document.
• Download a previously existing document.