How To Configure Java Heap Size Inside a Docker Container

1. Overview

When we run Java within a container, we may wish to tune it to make the best use of the available resources.

In this tutorial, we’ll see how to set JVM parameters in a container that runs a Java process. Although the following applies to any JVM setting, we’ll focus on the common -Xmx and -Xms flags.

We’ll also look at common issues containerizing programs that run with certain versions of Java and how to set flags in some popular containerized Java applications.

2. Default Heap Settings in Java Containers

The JVM is pretty good at determining appropriate default memory settings.

In the past, the JVM was not aware of the memory and CPU allocated to the container. So, Java 10 introduced a new setting: +UseContainerSupport (enabled by default) to fix the root cause, and developers backported the fix to Java 8 in 8u191. The JVM now calculates its memory based on the memory allocated to the container.

However, we may still wish to change the settings from their defaults in certain applications.

2.1. Automatic Memory Calculation

When we don’t set -Xmx and -Xmx parameters, the JVM sizes the heap based on the system specifications.

Let’s look at that heap size:

$ java -XX:+PrintFlagsFinal -version | grep -Ei "maxheapsize|maxram"

This outputs:

openjdk version "15" 2020-09-15
OpenJDK Runtime Environment AdoptOpenJDK (build 15+36)
OpenJDK 64-Bit Server VM AdoptOpenJDK (build 15+36, mixed mode, sharing)
   size_t MaxHeapSize      = 4253024256      {product} {ergonomic}
 uint64_t MaxRAM           = 137438953472 {pd product} {default}
    uintx MaxRAMFraction   = 4               {product} {default}
   double MaxRAMPercentage = 25.000000       {product} {default}
   size_t SoftMaxHeapSize  = 4253024256   {manageable} {ergonomic}

Here, we see that the JVM sets its heap size to approximately 25% of the available RAM. In this example, it allocated 4GB on a system with 16GB.

For the purposes of testing, let’s create a program that prints the heap sizes in megabytes:

public static void main(String[] args) {
  int mb = 1024 * 1024;
  MemoryMXBean memoryBean = ManagementFactory.getMemoryMXBean();
  long xmx = memoryBean.getHeapMemoryUsage().getMax() / mb;
  long xms = memoryBean.getHeapMemoryUsage().getInit() / mb;
  LOGGER.log(Level.INFO, "Initial Memory (xms) : {0}mb", xms);
  LOGGER.log(Level.INFO, "Max Memory (xmx) : {0}mb", xmx);
}

Let’s place that program in an empty directory, in a file named PrintXmxXms.java.

We can test it on our host, assuming we have an installed JDK. In a Linux system, we can compile our program and run it from a terminal opened on that directory:

$ javac ./PrintXmxXms.java
$ java -cp . PrintXmxXms

On a system with 16Gb of RAM, the output is:

INFO: Initial Memory (xms) : 254mb
INFO: Max Memory (xmx) : 4,056mb

Now, let’s try that in some containers.

2.2. Before JDK 8u191

Let’s add the following Dockerfile in the folder that contains our Java program:

FROM openjdk:8u92-jdk-alpine
COPY *.java /src/
RUN mkdir /app \
    && ls /src \
    && javac /src/PrintXmxXms.java -d /app
CMD ["sh", "-c", \
     "java -version \
      && java -cp /app PrintXmxXms"]

Here we’re using a container that uses an older version of Java 8, which predates the container support that’s available in more up-to-date versions. Let’s build its image:

$ docker build -t oldjava .

The CMD line in the Dockerfile is the process that gets executed by default when we run the container. Since we didn’t provide the -Xmx or -Xms JVM flags, the memory settings will be defaulted.

Let’s run that container:

$ docker run --rm -ti oldjava
openjdk version "1.8.0_92-internal"
OpenJDK Runtime Environment (build 1.8.0_92-...)
OpenJDK 64-Bit Server VM (build 25.92-b14, mixed mode)
Initial Memory (xms) : 198mb
Max Memory (xmx) : 2814mb

Let’s now constrain the container memory to 1GB.

$ docker run --rm -ti --memory=1g oldjava
openjdk version "1.8.0_92-internal"
OpenJDK Runtime Environment (build 1.8.0_92-...)
OpenJDK 64-Bit Server VM (build 25.92-b14, mixed mode)
Initial Memory (xms) : 198mb
Max Memory (xmx) : 2814mb

As we can see, the output is exactly the same. This proves the older JVM does not respect the container memory allocation.

2.3. After JDK 8u130

With the same test program, let’s use a more up to date JVM 8 by changing the first line of the Dockerfile:

FROM openjdk:8-jdk-alpine

We can then test it again:

$ docker build -t newjava .
$ docker run --rm -ti newjava
openjdk version "1.8.0_212"
OpenJDK Runtime Environment (IcedTea 3.12.0) (Alpine 8.212.04-r0)
OpenJDK 64-Bit Server VM (build 25.212-b04, mixed mode)
Initial Memory (xms) : 198mb
Max Memory (xmx) : 2814mb

Here again, it is using the whole docker host memory to calculate the JVM heap size. However, if we allocate 1GB of RAM to the container:

$ docker run --rm -ti --memory=1g newjava
openjdk version "1.8.0_212"
OpenJDK Runtime Environment (IcedTea 3.12.0) (Alpine 8.212.04-r0)
OpenJDK 64-Bit Server VM (build 25.212-b04, mixed mode)
Initial Memory (xms) : 16mb
Max Memory (xmx) : 247mb

This time, the JVM calculated the heap size based on the 1GB of RAM available to the container.

Now we understand how the JVM calculates its defaults and why we need an up-to-date JVM to get the correct defaults, let’s look at customizing the settings.

3. Memory Settings in Popular Base Images

3.1. OpenJDK and AdoptOpenJDK

Instead of hard-coding the JVM flags directly on our container’s command, it’s good practice to use an environment variable such as JAVA_OPTS. We use that variable within our Dockerfile, but it can be modified when the container is launched:

FROM openjdk:8u92-jdk-alpine
COPY src/ /src/
RUN mkdir /app \
 && ls /src \
 && javac /src/com/baeldung/docker/printxmxxms/PrintXmxXms.java \
    -d /app
ENV JAVA_OPTS=""
CMD java $JAVA_OPTS -cp /app \ 
    com.baeldung.docker.printxmxxms.PrintXmxXms

Let’s now build the image:

$ docker build -t openjdk-java .

We can choose our memory settings at runtime by specifying the JAVA_OPTS environment variable:

$ docker run --rm -ti -e JAVA_OPTS="-Xms50M -Xmx50M" openjdk-java
INFO: Initial Memory (xms) : 50mb
INFO: Max Memory (xmx) : 48mb

We should note that there is a slight difference between the -Xmx parameter and the Max memory reported by the JVM. This is because Xmx sets the maximum size of the memory allocation pool, which includes the heap, the garbage collector’s survivor space, and other pools.

3.2. Tomcat 9

A Tomcat 9 container has its own startup scripts, so to set JVM parameters, we need to work with those scripts.

The bin/catalina.sh script requires us to set the memory parameters in the environment variable CATALINA_OPTS.

Let’s first create a war file to deploy to Tomcat.

Then, we’ll containerize it using a simple Dockerfile, where we declare the CATALINA_OPTS environment variable:

FROM tomcat:9.0
COPY ./target/*.war /usr/local/tomcat/webapps/ROOT.war
ENV CATALINA_OPTS="-Xms1G -Xmx1G"

Then we build the container image and run it:

$ docker build -t tomcat .
$ docker run --name tomcat -d -p 8080:8080 \
  -e CATALINA_OPTS="-Xms512M -Xmx512M" tomcat

We should note that when we run this, we’re passing a new value to CATALINA_OPTS. If we don’t provide this value, though, we gave some defaults in line 3 of the Dockerfile.

We can check the runtime parameters applied and verify that our options -Xmx and -Xms are there:

$ docker exec -ti tomcat jps -lv
1 org.apache.catalina.startup.Bootstrap <other options...> -Xms512M -Xmx512M

4. Using Build Plugins

Maven and Gradle offer plugins that allow us to create container images without a Dockerfile. The generated images can generally be parameterized at runtime through environment variables.

Let’s look at a few examples.

4.1. Using Spring Boot

Since Spring Boot 2.3, the Spring Boot Maven and Gradle plugins can build an efficient container without a Dockerfile.

With Maven, we add them to a <configuration> block within the spring-boot-maven-plugin:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <groupId>com.baeldung.docker</groupId>
  <artifactId>heapsizing-demo</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <!-- dependencies... -->
  <build> 
    <plugins> 
      <plugin> 
        <groupId>org.springframework.boot</groupId> 
        <artifactId>spring-boot-maven-plugin</artifactId> 
        <configuration>
          <image>
            <name>heapsizing-demo</name>
          </image>
   <!-- 
    for more options, check:
    https://docs.spring.io/spring-boot/docs/2.4.2/maven-plugin/reference/htmlsingle/#build-image 
   -->
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

To build the project, run:

$ ./mvnw clean spring-boot:build-image

This will result in an image named <artifact-id>:<version>. In this example demo-app:0.0.1-SNAPSHOT. Under the hood, Spring Boot uses Cloud Native Buildpacks as the underlying containerization technology.

The plugin hard-codes the memory settings of the JVM. However, we can still override them by setting the environment variables JAVA_OPTS or JAVA_TOOL_OPTIONS:

$ docker run --rm -ti -p 8080:8080 \
  -e JAVA_TOOL_OPTIONS="-Xms20M -Xmx20M" \
  --memory=1024M heapsizing-demo:0.0.1-SNAPSHOT

The output will be similar to this:

Setting Active Processor Count to 8
Calculated JVM Memory Configuration: [...]
[...]
Picked up JAVA_TOOL_OPTIONS: -Xms20M -Xmx20M 
[...]

4.2. Using Google JIB

Just like the Spring Boot maven plugin, Google JIB creates efficient Docker images without a Dockerfile. The Maven and Gradle plugins are configured in a similar fashion. Google JIB also uses the environment variable JAVA_TOOL_OPTIONS as the JVM parameters’ overriding mechanism.

We can use the Google JIB Maven plugin in any Java framework capable of generating executable jar files. For example, it’s possible to use it in a Spring Boot application in place of the spring-boot-maven plugin to generate container images:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    
    <!-- dependencies, ... -->

    <build>
        <plugins>
            <!-- [ other plugins ] -->
            <plugin>
                <groupId>com.google.cloud.tools</groupId>
                <artifactId>jib-maven-plugin</artifactId>
                <version>2.7.1</version>
                <configuration>
                    <to>
                        <image>heapsizing-demo-jib</image>
                    </to>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

The image is built using the maven jib:DockerBuild target:

$ mvn clean install && mvn jib:dockerBuild

We can now run it as usual:

$ docker run --rm -ti -p 8080:8080 \
-e JAVA_TOOL_OPTIONS="-Xms50M -Xmx50M" heapsizing-demo-jib
Picked up JAVA_TOOL_OPTIONS: -Xms50M -Xmx50M
[...]
2021-01-25 17:46:44.070  INFO 1 --- [           main] c.baeldung.docker.XmxXmsDemoApplication  : Started XmxXmsDemoApplication in 1.666 seconds (JVM running for 2.104)
2021-01-25 17:46:44.075  INFO 1 --- [           main] c.baeldung.docker.XmxXmsDemoApplication  : Initial Memory (xms) : 50mb
2021-01-25 17:46:44.075  INFO 1 --- [           main] c.baeldung.docker.XmxXmsDemoApplication  : Max Memory (xmx) : 50mb

5. Conclusion

In this article, we covered the need to use an up-to-date JVM to get default memory settings that work well in a container.

We then looked at best practices for setting -Xms and -Xmx in custom container images and how to work with existing Java application containers to set the JVM options in them.

Finally, we saw how to advantage of build tools to manage the containerization of a Java application.