Configure and adjust heap size
This guide shows how to set the maximum heap size for the Java Virtual Machine (JVM) that runs the Deephaven server, and how to check and limit the memory that Docker containers can use.
The JVM heap is the memory that the JVM uses for objects, including the data of in-memory tables. The JVM option -Xmx sets the maximum heap size. For example, -Xmx8g sets the maximum to 8 GiB.
Where you set -Xmx depends on how you installed Deephaven:
- Pre-built images run in Docker containers. Set the heap size with the
START_OPTSenvironment variable. - Source builds start the server with Gradle. Set the heap size with
START_OPTSor a Gradle property.
The sections on container limits, the Docker Desktop memory cap, and Docker container memory apply only to the pre-built Docker image.
Set the heap size
If you set a container memory limit (see Limit container resources), keep -Xmx below that limit. The JVM also uses memory outside the heap. The -Xmx8g examples on this page assume a limit above 8 GiB, so they do not fit the 6000M limit in that section.
Pre-built images
Set START_OPTS in the environment of the service that runs the Deephaven server image. The example Compose files name that service deephaven:
Then start Deephaven again, as described in Start the application.
The example Compose files set START_OPTS=-Xmx4g. The published server-slim image does not set a heap size. If you do not set -Xmx, the JVM uses its default maximum heap, which is 25% of the memory the JVM can use: the container's limit if you set one, or the Docker host's memory if you do not.
To set the heap size without Docker Compose, add --env START_OPTS=-Xmx8g to the docker create command, then start the container:
If a container named deephaven already exists, remove it first with docker rm -f deephaven, as described in Modify the deployment, or pass a different --name.
Source builds
Set START_OPTS in the shell where you start the server. The Gradle run task reads it:
You can also pass the option as a Gradle property:
Limit container resources
This section applies to the pre-built Docker image.
To limit a container's memory and CPU, set deploy.resources for its service in your Docker Compose YAML file:
If you do not need the deploy block, you can set the same limits directly on the service with mem_limit, mem_reservation, and cpus:
Set -Xmx below the memory limit. The JVM also uses memory outside the heap, such as thread stacks and metaspace, which stores class metadata. That memory counts against the limit. For example, use -Xmx4g with a 6000M limit.
Docker Desktop memory cap
This section applies to the pre-built Docker image.
Docker Desktop also caps the memory that its containers can use. Keep the container limits you set in Limit container resources below this cap.
To change the cap, open Docker Desktop's settings and adjust Memory under Resources > Advanced.
On Windows with the Windows Subsystem for Linux (WSL 2) backend, set the limit in the .wslconfig file instead.
Docker Engine on Linux uses the host's memory directly, so it has no separate limit.
Monitor Docker container memory
This section applies to the pre-built Docker image.
To see your Docker configuration, run in a terminal:
To see the memory that running containers use, run the Docker stats built-in command:
This shows the live memory usage of all active containers, as well as each container's memory limit. A container with no limit set shows the memory available to Docker.
The MEM USAGE / LIMIT column shows values such as 20.00MiB / 5.804GiB. In that value, the first number is the RAM the container uses, and the second is its limit. For example, a container that uses 20.00MiB of RAM out of its 5.804GiB limit has room to grow. While your session runs, watch this column to see which containers might need more memory.