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.
Before you start
Section titled “Before you start”- 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.
Documents
Section titled “Documents”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.
Several tenants
Section titled “Several tenants”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.
License
Section titled “License”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.
Reports, stamps and LDAP
Section titled “Reports, stamps and LDAP”- 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.ldapand theldap.*keys) are carried over to the newopenkm.propertieswith 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
tomcatsymlink 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. Typeyto 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.
Search index
Section titled “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.
After the migration: clean-up
Section titled “After the migration: clean-up”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 (
openkmon Linux,OpenKMon 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; thetomcatsymlink 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.homeorrepository.*.homeinopenkm.properties): OpenKM 8.2 uses them as they are. Don’t delete them.
The console summary and
OKMMigrator.logsay how many files were hardlinked and how many copied. To check it on Linux,ls -lshows a link count of 2 or more on a hardlinked file. -
Leftovers:
OKMMigrator.jar,OKMMigrator.log,OKMInstaller.jarandOKMInstaller.login the base directory, andopenkm.properties.8.1.24(a copy of the old settings) in the Tomcat 10 folder can be deleted. KeepOKMUpdater.jarfor future updates.
Command-line parameters
Section titled “Command-line parameters”| 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 something goes wrong
Section titled “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.