How to move to another server

Caution

Although the system should not be affected, before performing this kind of action, we recommend having 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 procedures.

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 (the $TOMCAT_HOME folder). This user is usually named “openkm” (more info at Installing on Ubuntu and Debian (Manual)), but another may be chosen during installation.
• Update the OS.

Stop the OpenKM service

It is important that, while moving the data between the two servers, no changes occur 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

The database connection is configured in the “openkm.properties” file (in the $TOMCAT_HOME folder). In the sample below, 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 databases. 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 databases. 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 located elsewhere. 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 at the destination (otherwise, you will need to take extra configuration steps).
• Set permissions 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 this as root):

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

Configure the service on the new server

• Copy the file /etc/init.d/openkm to the new server at 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 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 (Manual)):

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

Start the 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 execute a repository checker (this action may take a long time to complete).

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.