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
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.
As always, the source code for the examples is available over on GitHub.