Backup and restore

One of the most important things to have is an up-to-date 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.

Note

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 other information, folders, document structure, metadata, etc., are stored in a database.

In that case:

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

Note

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. Note that, from OpenKM version 8.1.x, the Lucene indexes path location on the file system is not managed by “repository.home”. For more information, take a look at the Change repository home.

Tip

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:

• Stop Tomcat
• Back up the database
  • In case of MariaDB, please visit Full Backup and Restore with Mariabackup
  • In case of PostgreSQL, please visit PostgreSQL Backup and Restore
  • In case of SQL Server, please visit Create a Full Database Backup
  • In case of MySQL, please visit MySQL Backup and Recovery
• Back up the Tomcat or repository folder
• Start Tomcat

Note

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

Caution

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. However, we do not recommend this method of backing up; we suggest incremental backup solutions for medium to large repositories.

Linux detailed steps

You can follow these steps to back up and restore if you have OpenKM configured with MySQL or MariaDB. For other databases, check the corresponding commands.

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 deleting 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 created previously. On Ubuntu, if using MySQL or MariaDB, 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 statements:

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 perform a repository check. See Repository checker.

Windows detailed steps

You can follow these steps to back up and restore if you have OpenKM configured with MySQL or MariaDB. For other databases, check the corresponding commands.

Backup

• Stop the OpenKM service
• Create a database backup
  • In case of MariaDB, please visit Full Backup and Restore with Mariabackup
  • In case of PostgreSQL, please visit PostgreSQL Backup and Restore
  • In case of SQL Server, please visit Create a Full Database Backup
  • In case of MySQL, please visit MySQL Backup and Recovery
• Create a backup of the Tomcat folder
• Start the OpenKM service again

After that, you will have a ZIP archive with the whole OpenKM installation and the exported database. Please check before deleting 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 created previously. In the case of MySQL or MariaDB, please download from:

• https://mariadb.org/download/
• https://www.mysql.com/downloads/

Once installed, execute the following statements 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 perform a repository check. See Repository checker.

Backup scripts

• Linux backup and restore with BorgBackup (recommended)
• Linux backup and restore with rdiff-backup tool
• Linux backup and restore with rsync
• Linux backup and restore with Duplicity
• Linux backup with LFTP

Additional information

• Easy Automated Snapshot-Style Backups with Linux and Rsync
• BorgBackup documentation
• Rdiff-backup home page
• Duplicity Backup Howto