Configure the Marlin renderer

GeoServer WMS makes heavy use of Java's rendering facilities (the internal component is called a RenderingEngine). Java is a highly flexible environment allowing administrators to select an appropriate component for the workload being performed.

Correctly configuring the Marlin renderer is paramount to get the best performance. To do it, follow this step.

Reference:

• Enable the Marlin rasterizer

Check Rendering Engine

First we need to check that Marlin is used by GeoServer:

1. Navigate to the About > Service Status page.

2. From the Status tab check the Java Rendering Engine used:

   Java	Rendering Engine	Recommendation
   Java 8	sun.dc.DuctusRenderingEngine	This is the Java 8 default rendering engine, recommend installing Marlin.
   Java 8	org.marlin.pisces.MarlinRenderingEngine	Correctly configured with Marlin Rendering Engine
   Java 11	sun.java2d.marlin.DMarlinRenderingEngine	Java 11 defaults to MarlinRenderingEngine

3. From the Modules click on the Rendering Engine link.

   • Java 11 default

     Module Info
     Module Name: Rendering Engine
     Module ID: jvm
     Version: 11.0.7
     Component: java2d
     Message:
     
     Java 2D renderer configured with: PLATFORM DEFAULT
     

   • Java 8 default

     Module Name: Rendering Engine
     Module ID: jvm
     Version: 1.8.0_251
     Component: java2d
     Message:
     
     Java 2D renderer configured with: PLATFORM DEFAULT
     

   • Java 8 marlin

     Module Name: Rendering Engine
     Module ID: jvm
     Version: 1.8.0_251
     Component: java2d
     Message:
     
     Java 2D renderer configured with: org.marlin.pisces.MarlinRenderingEngine
     

Install Marlin Rendering Engine: Windows

To install and configure Marlin, follow these steps:

1. Go to the marlin releases page:

2. Scroll down to the Latest release, and expand the release Assets to locate and download the latest marlin jar.

   The jar contains the word "Unsafe" to indicate the use of internal Java API.

   Download assets for Marlin-renderer

   Marlin jar at the time of writing marlin-0.9.4.3-Unsafe.jar.

3. Copy the marlin jar file into Tomcat lib folder.

   Double check file permissions to ensure that tomcat can read the jar.

4. Include jar in the boot classpath, and configure sun.java2d.renderer to use Marlin.

   Java option:

   -Dcatalina.home=C:\Program Files\Apache Software Foundation\Tomcat 11.0
   -Dcatalina.base=C:\Program Files\Apache Software Foundation\Tomcat 11.0
   -Djava.io.tmpdir=C:\Program Files\Apache Software Foundation\Tomcat 11.0\temp
   -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
   -Djava.util.logging.config.file=C:\Program Files\Apache Software Foundation\Tomcat 11.0\conf\logging.properties
   -XX:SoftRefLRUPolicyMSPerMB=36000
   -XX:-UsePerfData
   -Xbootclasspath/a:lib/marlin-0.9.4.3-Unsafe.jar
   -Dsun.java2d.renderer=org.marlin.pisces.MarlinRenderingEngine
   

   System property:

   -Dcatalina.home=C:\Program Files\Apache Software Foundation\Tomcat 11.0
   -Dcatalina.base=C:\Program Files\Apache Software Foundation\Tomcat 11.0
   -Djava.io.tmpdir=C:\Program Files\Apache Software Foundation\Tomcat 11.0\temp
   -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
   -Djava.util.logging.config.file=C:\Program Files\Apache Software Foundation\Tomcat 11.0\conf\logging.properties
   -XX:SoftRefLRUPolicyMSPerMB=36000
   -XX:-UsePerfData
   -Xbootclasspath/a:lib/marlin-0.9.4.3-Unsafe.jar
   -Dsun.java2d.renderer=org.marlin.pisces.MarlinRenderingEngine
   

   Open the Tomcat configuration tool using Start > All Programs > Apache Tomcat > Tomcat Configuration. Click Configure and select the Java tab. Locate Java Options field, and add the following lines:

   -Dcatalina.home=C:\Program Files\Apache Software Foundation\Tomcat 11.0
   -Dcatalina.base=C:\Program Files\Apache Software Foundation\Tomcat 11.0
   -Djava.io.tmpdir=C:\Program Files\Apache Software Foundation\Tomcat 11.0\temp
   -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
   -Djava.util.logging.config.file=C:\Program Files\Apache Software Foundation\Tomcat 11.0\conf\logging.properties
   -XX:SoftRefLRUPolicyMSPerMB=36000
   -XX:-UsePerfData
   -Xbootclasspath/a:lib/marlin-0.9.4.3-Unsafe.jar
   -Dsun.java2d.renderer=org.marlin.pisces.MarlinRenderingEngine
   

   Note -X java options are listed before -D system properties.

5. If your application server is currently running, stop it and restart it.

6. Navigate to the About > Service Status page.

   • From the Status tab check the Java Rendering Engine

     To confirm the -Xbootclasspath/a setting include and was able to load the marlin jar.

   • From the Modules click on the Rendering Engine link.

     To confirm the -Dsun.java2d.renderer value has been recognized.

Install Marlin Rendering Engine: Linux

To install and configure Marlin, follow these steps:

1. Go to the marlin releases page:

2. Scroll down to the Latest release, and expand the release Assets to locate latest marlin jar.

   The jar contains the word "Unsafe" to indicate the use of internal Java API.

3. Download into the tomcat lib folder.

   cd lib
   wget https://github.com/bourgesl/marlin-renderer/releases/download/v0_9_4_3/marlin-0.9.4.3-Unsafe.jar
   

   Marlin jar at the time of writing marlin-0.9.4.3-Unsafe.jar.

4. Double check file permissions to ensure that tomcat can read the jar.

   chown tomcat:tomcat marlin-0.9.4.3-Unsafe.jar
   

5. Include jar in the boot classpath, and configure sun.java2d.renderer to use Marlin. To do, add the following config line to your Java options.

   For Tomcat running as a service, edit the service configuration:

   $ sudo vi /etc/systemd/system/tomcat.service
   

   Change the Environment="CATALINA_OPTS= line to

   Environment="CATALINA_OPTS=-Xms512M -Xmx10G -Xbootclasspath/a:/opt/tomcat/latest/lib/marlin-0.9.4.3-Unsafe.jar -server -XX:SoftRefLRUPolicyMSPerMB=36000 -XX:-UsePerfData -Dorg.geotools.referencing.forceXY=true -Dorg.geotoools.render.lite.scale.unitCompensation=true -Dsun.java2d.renderer=org.marlin.pisces.MarlinRenderingEngine"

   For Tomcat running from the command line, the required java option and system property in the bin/setenv.sh file:

   #!/bin/sh
   
   # Prepend JVM Options
   CATALINA_OPTS="-XX:SoftRefLRUPolicyMSPerMB=36000 -XX:-UsePerfData ${CATALINA_OPTS}"
   
   # Append system properties
   CATALINA_OPTS="${CATALINA_OPTS} -Dorg.geotools.referencing.forceXY=true"
   
   # Java 8: Marlin
   CATALINA_OPTS="-Xbootclasspath/a=lib/marlin-0.9.4.9-Unsafe-OpenJDK17.jar ${CATALINA_OPTS} -Dsun.java2d.renderer=org.marlin.pisces.MarlinRenderingEngine"
   

   Note

   -X java options must be listed before any -D system properties.

6. If your application server is currently running, stop it and restart it.

7. Navigate to the About > Service Status page.

   • From the Status tab check the Java Rendering Engine

     To confirm the -Xbootclasspath/a setting include and was able to load the marlin jar.

   • From the Modules click on the Rendering Engine link.

     To confirm the -Dsun.java2d.renderer value has been recognized.

Troubleshooting

Changing java startup options can prevent tomcat from starting.

Trouble shooting recommendations:

• Track the contents of the logs directory during startup.

  Linux and macOS:

  tail -f logs
  

  As an example catalina.out will report any unrecognized java options:

  Unrecognized option: -Xmistake
  Error: Could not create the Java Virtual Machine.
  Error: A fatal exception has occurred. Program will exit.