Setting the JVM

This section will discuss JVM (Java) settings for use with Boundless Server.

We recommend using the Oracle OpenJDK JVM with Boundless Server. Specifically, we recommend using Oracle OpenJDK 11 for all new installations.

The current GeoServer release requires a Java 8 or newer JVM.

When to use Java 8

While we recommend using Java 11, there are some situations in which you may need to use Java 8 instead.

If you are upgrading from a previous version of Boundless Server, continue to use Java 8 until you have verified that everything is working after the upgrade. After the upgrade is complete, you can switch to Java 11. If this introduces new issues, revert to Java 8.

If you are currently using Native JAI and/or Native ImageIO, the native bindings do not work on Java 11. Use Java 8.

If you are using the GeoMesa Extension, it does not yet support Java 11. Use Java 8.

Determining the current Java version

You may wish the verify the version of Java you are currently using.

Warning

It is possible to have multiple versions of the JRE installed, so just running java -version may not accurately reflect the version of the JRE being used by Boundless Server.

To confirm the version of Java used:

  1. Log in to the GeoServer admin interface.

  2. Navigate to the Server Status page, found on the left side under About & Status.

    ../../_images/jvm_serverstatuslink.png

    Click to open the Server Status page

  3. The JRE used by GeoServer is listed in the JVM Version entry.

    ../../_images/jvm_version.png

    JVM version

Changing to OpenJDK 11

Linux

  1. Download the Oracle JRE. In your browser, navigate to the Oracle OpenJDK 11 download page.

  2. Click the download link that matches your system:

    Linux/x64  tar.gz
    
  3. Extract the download file contents to your temporary directory or desktop.

  4. In a terminal, change to the directory that contains the extracted folder.

  5. Move this directory to /usr/lib/jvm (or wherever you’d like to place your JRE):

    sudo mv jdk-11.0.2 /usr/lib/jvm
    
  6. (Optional) Change your JAVA_HOME environment variable to point to this new directory:

    export $JAVA_HOME=/usr/lib/jvm/jdk-11.0.2
    
  7. Ensure your application server is using this new Java. Many application servers will pick up the system JAVA_HOME environment variable or require that their service definition be modified.

  8. If using Boundless Server packages (or just using Tomcat) open /etc/tomcat9/tomcat9.conf in a text editor.

  9. Near the top of the file, the JAVA_HOME variable is set. Change it to:

    # This is the $JAVA_HOME of JDK, not JRE. not needed if you've setup
    # the file "/etc/profile.d/java.sh" with this variable.
    JAVA_HOME=/usr/lib/jvm/jdk-11.0.2
    

    Note

    Make sure the line is uncommented (does not start with #).

  10. Save and close the file.

  11. Restart Tomcat.

  12. Boundless Server should now be using the new version of Java. Verify in GeoServer by navigating to the Server Status page.

    ../../_images/jdk11_status.png

    JVM Version showing OpenJDK 11

  13. On the line named JVM Version, you should see the Oracle JRE. (For historical reasons, it will be shown as “Java HotSpot.”)

Windows application servers

If running Boundless Server in an application server on a Windows system:

  1. Download the Oracle JRE. In your browser, navigate to the Oracle OpenJDK 11 download page.

  2. Click the download link that matches your system:

    Windows/x64  zip
    
  3. Extract the download file contents to your temporary directory or desktop.

  4. Move this directory to C:\Program Files\Java (or wherever you’d like to place your JRE).

  5. (Optional) Change your JAVA_HOME environment variable to point to this new directory. From the System Control Panel select Advanced System Settings. From the System Properties dialog navigate to the Advanced Tab and click Environment Variables. Define a System Variable by clicking New and entering:

    Variable name Variable value
    JAVA_HOME C:\Program Files\Java\jdk-11.0.2
  6. Restart your application server.

  7. Make sure that your application server is using this new Java. It may be reading the JAVA_HOME environment variable, or you may need to consult your application server documentation.

  8. Boundless Server should now be using the new version of Java. Verify in GeoServer by navigating to the Server Status page.

    ../../_images/jdk11_status.png

    GeoServer Server Status page showing OpenJDK 11

Note

Read more about installing Java on Windows.

Changing to OpenJDK 8

Linux

  1. Download the AdoptOpenJDK JRE. In your browser, navigate to the AdoptOpenJDK download page.

  2. Choose OpenJDK 8 (LTS) for version and HotSpot for JVM.

  3. Select the platform that matches your system, and click the Download JRE button.

  4. Extract the download file contents to your temporary directory or desktop.

  5. In a terminal, change to the directory that contains the extracted folder.

  6. Move this directory to /usr/lib/jvm (or wherever you’d like to place your JRE):

    sudo mv jdk8u202-b08-jre /usr/lib/jvm
    
  7. (Optional) Change your JAVA_HOME environment variable to point to this new directory:

    export $JAVA_HOME=/usr/lib/jvm/jdk8u202-b08-jre
    
  8. Ensure your application server is using this new Java. Many application servers will pick up the system JAVA_HOME environment variable or require that their service definition be modified.

  9. If using Boundless Server packages (or just using Tomcat) open /etc/tomcat9/tomcat9.conf in a text editor.

  10. Near the top of the file, the JAVA_HOME variable is set. Change it to:

    # This is the $JAVA_HOME of JDK, not JRE. not needed if you've setup
    # the file "/etc/profile.d/java.sh" with this variable.
    JAVA_HOME=/usr/lib/jvm/jdk8u202-b08-jre
    

    Note

    Make sure the line is uncommented (does not start with #).

  11. Save and close the file.

  12. Restart Tomcat.

  13. Boundless Server should now be using the new version of Java. Verify in GeoServer by navigating to the Server Status page.

    ../../_images/jdk8_status.png

    JVM Version showing AdoptOpenJDK 8

Windows application servers

If running Boundless Server in an application server on a Windows system:

  1. Download the AdoptOpenJDK JRE. In your browser, navigate to the AdoptOpenJDK download page.

  2. Choose OpenJDK 8 (LTS) for version and HotSpot for JVM.

  3. Select the platform that matches your system, and click the Download JRE button.

  4. Extract the download file contents to your temporary directory or desktop.

  5. Move this directory to C:\Program Files\Java (or wherever you’d like to place your JRE).

  6. (Optional) Change your JAVA_HOME environment variable to point to this new directory. From the System Control Panel select Advanced System Settings. From the System Properties dialog navigate to the Advanced Tab and click Environment Variables. Define a System Variable by clicking New and entering:

    Variable name Variable value
    JAVA_HOME C:\Program Files\Java\jdk8u202-b08-jre
  7. Restart your application server.

  8. Make sure that your application server is using this new Java. It may be reading the JAVA_HOME environment variable, or you may need to consult your application server documentation.

  9. Boundless Server should now be using the new version of Java. Verify in GeoServer by navigating to the Server Status page.

    ../../_images/jdk8_status.png

    GeoServer Server Status page showing AdoptOpenJDK 8

  10. On the line named JVM Version, you should see the Oracle JRE. (For historical reasons, it will be shown as “Java HotSpot.”)

Note

Read more about installing Java on Windows.

Setting the default JVM using update-alternatives

If you used linux packages to install different versions of java and are using the Boundless Server packages you can use the update-alternatives command to set the default java for your system.

Note

This method may change the java version other applications are using on your server. This may cause issues.

  1. Run the command;

    update-alternatives --config java
    
  2. You will be presented with a list of installed Java versions. Choose the one you would like to use.

    There are 2 programs which provide 'java'.
    
       Selection    Command
    -----------------------------------------------
     *+ 1           /usr/lib/jvm/jre-1.8.0-openjdk.x86_64/bin/java
        2           /usr/java/jre1.8.0_101/bin/java
    
    Enter to keep the current selection[+], or type selection number:
    
  3. Verify by running;

    java -version
    
  4. Restart Tomcat