Configure Java Runtime

A guide to how to set up an external JRE to run the Akana Platform.

Note: These instructions are only applicable for versions earlier than 2019.0.0. These steps are not valid for version 2019.0.0.

Table of Contents

  1. Introduction
  2. Find Your Java installation
  3. Copy the provider jar file
  4. Update the java.security file
  5. Update the setDEMSenv.sh/setDEMSenv.bat file

Introduction

In versions earlier than 2019.0.0, to use an external JRE (that is, not provided by Akana), you will have to ensure that you extend the Java security providers with the Bouncy Castle provider. This provider ships with the Akana Plaform in the /jreupdate folder.

These instructions assume that you chose an installation ZIP file that does not include a bundled JRE.

If you have an existing installation and you're not sure which JRE version the platform is using, you can check it in your installation. See Checking the JRE version (troubleshooting guide).

Find your Java installation

Depending on your operating system and how you installed your JRE, there might be different ways of finding it. It's typically fairly easy to find, but if you're on a mac you may find this command useful:

/usr/libexec/java_home

This will show you the folder where Java is installed, and will also tell you what you should set in your profile for the JAVA_HOME variable. In fact, this is probably a good time to set JAVA_HOME.

Once you've found your installation, you can continue with the process of adding the Bouncy Castle security provider. On a mac, it will likely look something like this:

Library/Java/JavaVirtualMachines/jdk1.8.0_91.jdk/Contents/Home

Copy the provider jar file

Copy the following file from your Akana Platform installation folder to the jre/lib/ext folder in your Java installation.

  • File: bcprov-jdkon-XXX.jar
  • Source folder: $AKANAROOT/jreupdate/ext
  • Target folder: jre/lib/ext
  • Example:
    sudo cp ~/Downloads/akana-platform-8.1.39/jreupdate/ext/bcprov-jdk15on-147.jar $JAVA_HOME/jre/lib/etc/

Update the java.security file

  1. Open the sample java.security file from your Akana Platform installation (in jreupdate/security).
  2. Find and copy the line that references the Bouncy Castle provider, something like this:
    security.provider.10=org.bouncycastle.jce.provider.BouncyCastleProvider
  3. Then edit the java.security file (it's normally a root owned file, so remember to use sudo) in your Java installation $JAVA_HOME/jre/lib/security/java.security and add the line you just copied to the end of the provider list.

    NOTE: make sure you change the number of the provider to be one greater than the previous entry in the list. In the case of the default Apple JRE installation you will see a list ending in 10, and so will need to use security.provider.11=....

And that's it—your JRE is ready to use with the Akana Platform.

As a reminder, from version 2019.0.0 the above instructions are not applicable.

Update the setDEMSenv.sh/setDEMSenv.bat file

In an environment where you're using the default packaged JRE version and then want to switch to using your own JRE at an external path, there is one other file in the Akana install directory that you'll need to change, so that it will not override your JAVA_HOME path when the container is started using the startup script.

In Akana, the startup script used to start the Akana container executes the setDEMSEnv file as a part of the startup process, and this setDEMSEnv file sets the JAVA_HOME variable to use the JRE version installed with the product. This resets/overrides the JAVA_HOME value set at the operating system level.

To avoid that and to use the JAVA_HOME path (pointing to an external JRE) already set at the operating system level, you'll need to comment a few lines of code in the setDEMSEnv file.

Follow the steps below.

For containers on Linux
  1. From your install directory, open the setDEMSenv.sh file with any text editor(/{install_folder}/bin/setDEMSenv.sh).
  2. Edit the file to comment out the following lines:
    if [ -d $RELEASE_ROOT/jre ] ; then
    JAVA_HOME=$RELEASE_ROOT/jre
    export JAVA_HOME
    fi
  3. Save and close the file.
  4. Restart the container.
For containers on Windows
  1. From your install directory, open the setDEMSEnv.bat file with any text editor (\{install_folder}\bin\setDEMSenv.bat).
  2. Edit the file to comment out the following lines:
    IF EXIST "%RELEASE_ROOT%/jre" (
    	set JAVA_HOME=%RELEASE_ROOT%/jre
    )
  3. Save and close the file.
  4. Restart the container.

And that's it! Your Akana Platform will run on the external JRE you configured.

As a reminder, from version 2019.0.0 the above instructions are not applicable.

back to top