Migration from 8.1 to 8.2

The OpenKM migration tool upgrades an OpenKM 8.1.23 instance directly to 8.2.9, skipping the intermediate versions. It installs Tomcat 10 and OpenKM 8.2.9 on the same database used by the 8.1.23 instance, upgrades the database schema and carries over your openkm.properties settings. It takes 10 to 20 minutes, depending on the size of your database. You can download it from https://download.openkm.com/okm/OKMMigrator.jar.

Caution

The migration tool requires Java 17 or 21, the same Java versions required by OpenKM 8.2. The java command in the PATH must be one of these versions, because it is also used to run the installer.

Before you start

• Your instance must be running exactly version 8.1.23. If it’s on an earlier 8.1.x version, update it first with the Updater utility. The tool checks the version and stops without changing anything if it is not 8.1.23.
• Take a full backup of the database and the repository (documents) before continuing. The tool does not create any backup itself, and the schema change cannot be undone.
• Have your OpenKM download portal user and password ready, the same ones you use for the installer. They are needed to download Tomcat 10 and OpenKM 8.2.9.
• The server needs access to https://download.openkm.com. The tool downloads OKMInstaller.jar and OKMUpdater.jar from there if they are not already in the installation folder.

Note

If the current Tomcat 9 is running, the tool stops it before starting the migration.

Steps

• Download the tool into the base directory of your installation (the folder where the tomcat symlink is located):

$ cd /opt/openkm
$ wget https://download.openkm.com/okm/OKMMigrator.jar

• Run it from there:

$ java -jar OKMMigrator.jar

• It will ask for your download portal user and password, and then for a confirmation ([y/N]) reminding you about the backup. Type y to continue.
• From there, it’s automatic. You’ll see the progress on screen (Tomcat 10 installation, schema upgrade, Flyway activation). It’s normal for it to take several minutes and restart Tomcat a number of times.
• When it’s done, you’ll see:

### MIGRATION: DONE - now running OpenKM 8.2.9 at http://localhost:8080 ###
Migration completed successfully.

• Verify that you can log in normally and that your documents are still there.
• Rebuild the search index from Administration > Utilities > Rebuild indexes. See Search index.

Search index

OpenKM 8.1 (Lucene 8) and OpenKM 8.2 (Lucene 9) use incompatible search index formats, so the migrated instance starts with an empty search index. Documents, folders and their metadata are not affected and can be browsed normally, but they won’t appear in search results until the index is rebuilt from Administration > Utilities > Rebuild indexes.

Caution

Do not copy the old repository/index folder into the new Tomcat: OpenKM 8.2 cannot read it and fails with Could not load codec 'Lucene87' the first time it writes to the index.

Command-line parameters

Parameter	Description
-p, –old-properties	Path to the openkm.properties file of the 8.1.23 installation. By default, ./tomcat/openkm.properties.
-d, –parent-dir	Folder where the new Tomcat 10 is installed. By default, the base directory of the 8.1.23 installation.
-f, –force	Skip the confirmation prompt (for non-interactive or scripted use).
--no-service	Tomcat is not configured as a service.
-h, –help	Show help information.

The default values cover the usual case: running the tool from the base directory of the installation, where the tomcat symlink created by the installer points to the 8.1.23 installation. For another folder layout, use both -p and -d.

If something goes wrong

If the tool stops with an error, it does not proceed any further. Save the full console output and the OKMMigrator.log file (it’s left in the folder you ran it from) and contact OpenKM support.