Personal development environment

The OpenKM personal development environment is distributed as a virtual machine image (OVA).

The personal development environment comes with everything you need to start working quickly:

• Linux Mint OS.
• OpenKM application installed.
• MariaDB database.
• Eclipse
  • Code samples.
  • Workflow samples.
• IReport
  • SQL samples.
  • Scripting samples.

Requirements

The virtual machine uses 2 core and 4GB of RAM, the host machine should have at least 4 core and 8GB of RAM.

Caution

We suggest stopping almost all applications while running the virtual machine.

We suggest installing it on a desktop computer rather than a laptop. It can work on a laptop with good hardware.

We suggest using an SSD to get extra performance in the virtual machine.

With some users, we have observed that running the virtual machine from a secondary disk provides extra performance; it seems some motherboards do not handle the OS and virtualization on the same hard disk well.

How to get the personal development environment

You can download the virtual machine file from the OpenKM download center.

• Go to https://download.openkm.com
• Click the “OpenKM Professional Download Center” button.
• Log in with your customer credentials.
• In the top menu, choose Tools.
• In Tools, ensure you have chosen OpenKM version 8.1.x.
• Click on the Open KM-PorDev.ova file.

Caution

The download link is sent by e-mail.

The link can be used only once.

You have 24 hours from when the e-mail is sent to use the link; after this time the link expires.

How to install

The OpenKM personal development environment can be installed on most virtual machine software like VirtualBox, VMware, and Hyper-V.

Caution

Because OVA (Open Virtual Appliance) is not 100% compatible with virtualization software, users of VMware usually need to make a few modifications to the file or extract the mkv to import the virtual machine.

If you are looking for a quick deployment, we encourage using VirtualBox.

If you decide on VirtualBox, follow the steps described in the next video https://www.youtube.com/watch?v=9ugBYf5ggu8&feature=emb_logo

License activation

Danger

The personal development environment must have an Internet connection to register the license.

Finally, the license for your personal development environment must be activated; to do so, follow these steps:

1- Open a terminal (the password for the user openkm is openkm).

2- Execute the following command

$> pdl-reset

3- Start the OpenKM service.

$> sudo service openkm start

4- Open an issue on the OpenKM customer support website. Share the application ID available on the administration home page.

How to upgrade the development environment

Caution

Because the virtual machine comes with OpenKM, jbpm-console, and compilation libraries, the upgrade process has at least three steps:

• Upgrade OpenKM
• Upgrade OpenKM compilation libraries
• Upgrade jbpm-console

Step 1 - OpenKM upgrade

• Close Eclipse.
• Start OpenKM as a service.

$> sudo su
$> service openkm start

• Upgrade the OpenKM tool as you would for any standard OpenKM installation. The process for upgrading the development environment is exactly the same as upgrading the standard OpenKM professional edition. More information at Updater utility.

$> cd /home/openkm/Development/tomcat
$> wget http://download.openkm.com/okm/OKMUpdater.jar
$> java -jar OKMUpdater.jar

Note

The latest OpenKM development environment comes with the update.sh script.

$> cd /home/openkm/Development/tomcat
$> ./update.sh

Step 2 - OpenKM compilation libraries upgrade

• Close Eclipse.
• Edit the download.sh script and set the latest OpenKM and jbpm-console versions in the header.

$> cd /home/openkm/Development/portable/lib
$> nano download.sh

Note

Sample script for version 7.1.22 (remember to set the correct JBPM version based on the compatibility table in the JBPM Console documentation section):

#!/bin/bash
OKM_VERSION="7.1.22"
JBPM_VERSION="1.8"

# Download OpenKM libraries
wget http://download.openkm.com/okm/portable/jar/openkm-${OKM_VERSION}-client.jar -O openkm-client.jar
wget http://download.openkm.com/okm/portable/jar/openkm-${OKM_VERSION}-jar-with-dependencies.jar -O openkm-jar-with-dependencies.jar

# Download jBPM libraries
wget http://download.openkm.com/okm/pro/workflow/jbpm-${JBPM_VERSION}-client.jar -O jbpm-client.jar
wget http://download.openkm.com/okm/pro/workflow/jbpm-${JBPM_VERSION}-jar-with-dependencies.jar -O jbpm-jar-with-dependencies.jar

• Execute the download.sh script.

$> ./download.sh

• Edit the register.sh script and set the latest OpenKM versions in the header.

$> nano register.sh

Note

Sample script for version 7.1.22 (remember to set the correct JBPM version based on the compatibility table in the JBPM Console documentation section):

#!/bin/bash
VERSION="7.1.22"
JBPM_VERSION="1.8"

# Register OpenKM libraries
mvn install:install-file -DgroupId=com.openkm -DartifactId=openkm -Dversion=${VERSION} -Dclassifier=client -Dpackaging=jar -Dfile=openkm-client.jar
mvn install:install-file -DgroupId=com.openkm -DartifactId=openkm -Dversion=${VERSION} -Dclassifier=jar-with-dependencies -Dpackaging=jar -Dfile=openkm-jar-with-dependencies.jar

# Register Jbpm libraries
mvn install:install-file -DgroupId=com.openkm -DartifactId=jbpm-console -Dversion=${JBPM_VERSION} -Dpackaging=jar -Dfile=jbpm-client.jar

• Execute the register.sh script.

$> ./register.sh

Step 3 - Jbpm-console upgrade

• First, check the correct jbpm-console version based on the compatibility table in the JBPM Console documentation section.
• Follow the steps described in the Migration guide.

Troubleshooting

Importing the OVA File into a Non–VirtualBox Virtual Machine

If you encounter issues importing the provided OVA file into a virtual machine platform other than VirtualBox, it is likely due to differences in virtualization formats. Since most VM vendors do not follow a standardized format, direct OVA imports between different platforms are often not supported.

To resolve this issue, follow these steps:

• Rename the OVA file extension from .ova to .tar.
• Extract the contents of the .tar archive using your preferred extraction tool.
• Inside the extracted files, locate the virtual disk image, typically with the extension .vmdk.
• Create a new virtual machine manually in your chosen virtualization platform.
• When prompted for a disk image, attach the extracted .vmdk file as the virtual disk.

This process effectively recreates the original virtual machine using the extracted disk image, making it compatible with non–VirtualBox environments.