Configure Java Runtime

A guide to how to set up the Akana Platform to use an external JRE rather than the version included with installation.

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

Table of Contents

  1. Introduction
  2. Configuring the Akana Platform to use an external JRE
    1. Find your Java installation
    2. Copy the provider jar file
    3. Update the java.security file
    4. Save the keystore/truststore and update the path
    5. Update the setDEMSenv.sh/setDEMSenv.bat file
  3. Configuring the Akana Platform to use a different embedded JRE version

Introduction

In versions prior to 2019.0.0, the Akana Platform is offered with with an embedded JRE that is part of the installation. Akana doesn't use the JAVA_HOME environment variable. Instead, it uses Java runtime, installed in the {platform_install}/jre installation folder. If you want to use a different JRE version, you can do either of two things:

Note: In versions earlier than 2019.0.0, to use an external JRE (that is, not the version provided by Akana), it's necessary to ensure that you extend the Java security providers with the Bouncy Castle provider. This provider ships with the Akana Platform in the /jreupdate folder.

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).

Configuring the Akana Platform to use an external JRE

Note: If you're pointing to an external version, choose an installation ZIP file that does not include a bundled JRE. The instructions below assume that you have done that.

To configure the platform to use an external JRE, follow these high-level steps:

  1. Find your Java installation
  2. Copy the provider jar file
  3. Update the java.security file
  4. Save the keystore/truststore and update the path
  5. Update the setDEMSenv.sh/setDEMSenv.bat file

Find your Java installation

Depending on your operating system and how you installed your JRE, there are different ways of finding it. If you're on a Mac you could use this command:

/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 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 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 $JAVA_HOME/lib/ext folder in your Java installation.

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

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 the following:
    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'll see a list ending in 10, so you'll need to use security.provider.11=....

Save the keystore/truststore and update the path

By default, when you install the Akana platform, the platform settings point to the default keystore/truststore location where the cacerts file is stored. This is inside the /{install_folder}/jre/lib/security folder, which is the packaged JRE.

The default settings are shown below.

Configuring the keystore and truststore location

If you change the JRE, you must also copy the cacerts file to a new location, and update the settings so that the container can find the certificates.

For example, you could create a new folder, /{install_folder}/keystore, and copy the /{install_folder}/jre/lib/security/cacerts file to the /{install_folder}/keystore folder.

Follow the steps below.

To create a new keystore/truststore location and update the platform settings
  1. Optional: check that the existing settings are the defaults. In the Akana Administration Console, choose Configuration. Find the com.soa.security category and note these two values:
    • bootstrap.keystore.location (default value: META-INF/keystore/keystore-default.jks)
    • bootstrap.truststore.location (default value: META-INF/keystore/keystore-default.jks)
  2. In your installation, copy the /{install_folder}/jre/lib/security folder to a safe place.
  3. In your installation, create a new folder, /{install_folder}/keystore.

    Note: the folder name used here is just an example. You can use a different name.

  4. Copy the /{install_folder}/jre/lib/security/cacerts file to the new folder you created in Step 3.
  5. In the Akana Administration Console, choose Configuration. Find the com.soa.security category and update these two settings to the new location:
    • bootstrap.keystore.location. New value in this example: file:///{install_folder}/keystore/cacerts.jks.
    • bootstrap.truststore.location New value in this example: file:///{install_folder}/keystore/cacerts.jks.
  6. Save the changes.
  7. Continue with the next step, Update the setDEMSenv.sh/setDEMSenv.bat file below.

Note: If you don't set up the new location for this file and update the properties as above, when you restart the container there will be issues due to missing certificates.

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

Configuring the Akana Platform to use a different embedded JRE version

Another approach for changing the JRE is to configure the product itself to use a different JRE.

One easy approach is given below.

Note: these instructions apply to versions prior to 2019.0.0 only. 2019.0.0 does not use the Bouncy Castle artifacts referenced below.

To change the JRE version that came with the product
  1. Rename the existing JRE folder; for example, rename {install_folder}/jre to {install_folder}/jre-old.
  2. Create a new jre folder ({install_folder}/jre) and install your new Java version there. The correct location of the java.exe file must be: {install_folder}/jre/bin/java.exe.
  3. Make the following additional changes:

back to top