How to move to another server

Caution

Although the system should not be affected, before doing 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 (Manual) 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 (Manual)), but the installation may have chosen a different one.
• Update the OS.

Stop OpenKM service

It is important that, while moving the data between the two servers, you do not perform any changes on the old server. That’s why it is 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

In the “openkm.properties” file (in the $TOMCAT_HOME folder), the database connection is configured. 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 (Manual) ).
• Copy the okmdb.sql file to the new server.
• Restore the backup.

The sample below explains how to restore the MySQL and 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 grants for the owner of 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-8.5.69

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 in the new server

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

Install third-party tools

Caution

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

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

• 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.

• In case the new server has less RAM than the old server, you need to check the $TOMCAT_HOME/bin/setenv.sh file and adapt it properly.
• 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 administration 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.