Backup and restore

One of the most important things to have is an updated backup of your OpenKM.

If you have followed the installation instructions, you have configured OpenKM to use a production-safe database and optionally set a path to the OpenKM repository data store.

OpenKM has several configurations, but for optimal performance, we recommend the following:

  • Use a default data store that saves binary information directly to the server disk ( in a non-human comprehensible format ).
  • All the other information, folders, document structure, metadata, etc., is stored in a database.

In that case:

  1. First, backup your database (make a SQL dump)
  2. Then, backup your data on the filesystem

By default, all documents are stored in $TOMCAT_HOME/repository. This default folder can be changed using the property "repository.home" in the file $TOMCAT_HOME/openkm.properties file. Remember from OpenKM version 8.1.x, the Lucene indexes path location in the file system is not managed by "repository.home". For more information, take a look at the Change repository home.

Although OpenKM supports hot backups of your data, it is recommended to stop Tomcat before starting the backup. Apply this good practice when possible.

Backup steps:

Performing the backup in that order (the database first, then the filesystem) will ensure backup consistency.

Contact support before starting the new instance to prevent license validation issues. It's important not to have both instances running simultaneously to avoid license validation problems.

An alternative to traditional backup methods is to export the whole repository from OpenKM Administration > Utilities > Repository export and choose metadata and history options. But we do not suggest this way of doing backups; we suggest some incremental backup solutions for medium to large repositories.

Linux detailed steps

You can follow these steps to backup and restore if you have OpenKM configured with MySQL or MariaDB. For other databases, check their corresponding command.

Backup

$ systemctl stop openkm
$ mysqldump -h localhost -u root -p okmdb > /path/to/openkm/okmdb.sql
$ zip -r /path/to/backup/okm-backup.zip /path/to/openkm
$ systemctl start openkm

After that, you will have a ZIP archive with the whole OpenKM installation and the exported database. Please, check before destroying this installation. We always recommend restoring the backup to ensure you have all the required files.

Restore

Please note that you must create the database if it wasn't made previously. In the case of MySQL or MariaDB and Ubuntu, use this command to install it:

$ sudo apt install mariadb-server

In the case of CentOS:

$ sudo yum install mariadb-server

And execute the following sentences:

CREATE USER 'openkm'@'localhost' IDENTIFIED BY 's3cr3t0';
CREATE DATABASE okmdb DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_bin;
GRANT ALL ON okmdb.* TO 'openkm'@'localhost' WITH GRANT OPTION;

Remember that the user and database names may be different in your case. Please, take a look at the installation report or check it at $TOMCAT_HOME/openkm.properties

Once created, restore the database and files:

$ unzip /path/to/backup/okm-backup.zip -d /path/to/restore
$ mysql -h localhost -u root -p okmdb < /path/to/restore/okmdb.sql 

Set the permissions according to the user who starts OpenKM:

$ sudo chown openkm:openkm /path/to/openkm -R

Install the required dependencies. In the case of Ubuntu:

$ sudo apt install xvfb imagemagick libreoffice tesseract-ocr

In the case of CentOS:

$ sudo yum install ImageMagick tesseract libreoffice libreoffice-headless

Once restored, verify file permissions, start OpenKM, and make a repository check. See Repository checker.

Windows detailed steps

You can follow these steps to backup and restore if you have OpenKM configured with MySQL or MariaDB. For other databases, check their corresponding command.

Backup

After that, you will have a ZIP archive with the whole OpenKM installation and the exported database. Please, check before destroying this installation. We always recommend restoring the backup to ensure you have all the required files.

Restore

Please note that you must create the database if it wasn't made previously. In the case of MySQL or MariaDB please download from:

Once installed, execute the following sentences to create the database user and OpenKM database:

CREATE USER 'openkm'@'localhost' IDENTIFIED BY 's3cr3t0';
CREATE DATABASE okmdb DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_bin;
GRANT ALL ON okmdb.* TO 'openkm'@'localhost' WITH GRANT OPTION;

Remember that the user and database names may be different in your case. Please, take a look at the installation report or check it at $TOMCAT_HOME/openkm.properties

Once created, restore the database and files:

C:\> unzip okm-backup.zip -d C:\
C:\> mysql -h localhost -u root -p okmdb < okmdb.sql 

Set the permissions according to the user who starts OpenKM.

Once restored, verify file permissions, start OpenKM, and make a repository check. See Repository checker.

Backup scripts

Additional information