Skip to content
Other versions

Loading…

Migration from 8.1 to 8.2

The OpenKM migration tool upgrades an OpenKM 8.1.24 instance directly to 8.2.10, skipping the intermediate versions. It installs Tomcat 10 and OpenKM 8.2.10 on the same database used by the 8.1.24 instance, upgrades the database schema and carries over your documents and 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.

  • Your instance must be running exactly version 8.1.24. 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.24.
  • 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.10.
  • 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.

If the documents are inside the Tomcat 9 folder (<tomcat>/repository, the default), the tool hardlinks them into the new Tomcat 10: they take no extra disk space and the originals are not modified. If the new Tomcat is on a different filesystem, they are copied instead. This covers the document contents, the extracted text, the preview cache and the OCR templates of each tenant. The search index is not carried over (see Search index).

Folders that openkm.properties places outside Tomcat (repository.home, repository.datastore.home, repository.extraction.home, repository.cache.home or repository.ocr.template.home) are not moved: OpenKM 8.2 keeps using them.

All tenants are migrated: the database is updated as a whole, and the folders of each tenant (tenant_1, tenant_2…) are carried over as described in Documents.

Your license must cover all your tenants. If it allows fewer tenants than the instance has, the license is not valid.

The migration upgrades the same database, so the license is migrated too: OpenKM 8.2 keeps the Installation ID of OpenKM 8.1 (and its offline license, if it has one). You don’t need to register a new license.

  • Stamps are kept as they are.
  • Reports are kept, but none of them works in OpenKM 8.2 until it is converted: OpenKM 8.2 uses JasperReports 7, which only reads its own JRXML format, not the JasperReports 6 one of OpenKM 8.1. Until then, running a report fails with “Unable to load report”. Open each report in Jaspersoft Studio 7, save it in the new format and upload it again in Administration > Reports. Reports that use OpenKM classes may also need changes.
  • LDAP or Active Directory authentication is kept: its settings (okm.authentication.ldap and the ldap.* keys) are carried over to the new openkm.properties with the rest of your custom settings. Check that LDAP users can log in.
  • Download the tool into the base directory of your installation (the folder where the tomcat symlink is located):
Terminal window
$ cd /opt/openkm
$ wget https://download.openkm.com/okm/OKMMigrator.jar
  • Run it from there:
Terminal window
$ 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.10 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.

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.

Once you have checked for a few days that OpenKM 8.2 works correctly (documents open, searches work after rebuilding the index, users log in normally), you can remove what is left of OpenKM 8.1. Until then, keep everything: it’s the only way back.

  • Service: nothing to do. The service keeps its name (openkm on Linux, OpenKM on Windows) and now starts OpenKM 8.2; the tool replaced the 8.1 one. With --no-service, no service was registered.

  • Database: nothing to delete. OpenKM 8.2 uses the same database, upgraded. Keep the backup you took before the migration for as long as your backup policy requires: it’s the only copy of the 8.1 database.

  • Old Tomcat 9 folder (for instance, /opt/openkm/tomcat-9.0.x; the tomcat symlink now points to the Tomcat 10 one): it can be deleted, but first check where OpenKM 8.2 keeps the documents (see Documents):

    • Hardlinked (same disk, the usual case): deleting the old folder removes only the 8.1 names of the files. OpenKM 8.2 keeps its own, so nothing is lost, but no disk space is freed for the documents either: they were never duplicated.
    • Copied (Tomcat 10 on another disk): the 8.1 files are a duplicate. Deleting the old folder frees that space.
    • Symlink (a folder of the 8.1 repository was a symbolic link, for instance to another disk): the new Tomcat has a link to the same place. Deleting the old Tomcat folder removes only the old link, but don’t delete the folder it points to: OpenKM 8.2 uses it.
    • Folders outside Tomcat (repository.home or repository.*.home in openkm.properties): OpenKM 8.2 uses them as they are. Don’t delete them.

    The console summary and OKMMigrator.log say how many files were hardlinked and how many copied. To check it on Linux, ls -l shows a link count of 2 or more on a hardlinked file.

  • Leftovers: OKMMigrator.jar, OKMMigrator.log, OKMInstaller.jar and OKMInstaller.log in the base directory, and openkm.properties.8.1.24 (a copy of the old settings) in the Tomcat 10 folder can be deleted. Keep OKMUpdater.jar for future updates.

Parameter Description
-p, –old-properties Path to the openkm.properties file of the 8.1.24 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.24 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.24 installation. For another folder layout, use both -p and -d.

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.