Configure the Deephaven production application

This guide describes the Deephaven production application's directory layout, its start script, and its bootstrap configuration. Bootstrap configuration is the small set of settings, such as the data, cache, and config directories, that the server reads at startup, before it reads any configuration file. Use this guide to change where Deephaven stores data, cache, and configuration files, to set the JVM heap and other startup options, and to find the directories the application ships with.

The Deephaven production application is the recommended way to run Deephaven in production, hence its name. It runs Deephaven directly from artifacts produced during each release. Download the artifacts from the GitHub releases page, under the assets list.

The production application gives you direct control over the server's JVM options, directories, and startup, but requires more setup and consideration of low-level details. Users who wish to get up and running without needing to worry about these details should consider Docker.

This guide assumes familiarity with installing and running the Deephaven production application. For an introductory guide on installing and running, see Install and run the Deephaven production application.

Prerequisites

The production application requires Java 17 or later. Deephaven recommends Java 21, a long-term support (LTS) release. A Python console, the default, also requires Python 3.9 or later. To run a Groovy console instead, see Choose the console type. For the full list of requirements, see the production application prerequisites.

The production application also requires Linux or macOS. It does not run natively on Windows, so Windows users need Windows Subsystem for Linux v2 (WSL 2).

Directory layout

The inner structure of the application is a root directory of the form server-jetty-<version>/ with further subdirectories:

• bin/: Contains a start script used to launch the server.
• lib/: Contains all of the JAR files that form the application classpath.
• etc/: Contains the Java Virtual Machine (JVM) option files and the compiler directives file (dh-compiler-directives.txt) that the start script always loads.

For the option file used for your Java version, see JAVA_OPTS under Environment variables.

Configure the start script

What the start script does

The start script collects the arguments, assembles the classpath, and executes a shell command that looks something like:

• <required-opts> are JVM settings that the start script always passes before JAVA_OPTS and START_OPTS. You can't remove them without editing the script.
• A -D property in START_OPTS overrides a -D property of the same name in the script's default JVM options.
• <classpath> is the constructed classpath. You can't change it, but you can prepend entries with the EXTRA_CLASSPATH environment variable.

Environment variables

The table below lists the environment variables that the start script and the server read. Set them in the shell environment before you run the start script. The server's bootstrap environment variables are in Configure server directories.

Set JVM system properties in START_OPTS. By default, set Deephaven configuration properties in a deephaven.prop file in the config directory. Environment variables can't be set in deephaven.prop.

Set the JVM heap size

The -Xmx option sets the maximum heap size. It is a JVM option, so set it through START_OPTS. For example, this command sets the maximum heap size to 8 GB for a single run:

Choose the console type

To start a Groovy console, set -Ddeephaven.console.type=groovy through START_OPTS, for example:

See configuration properties for the deephaven.console.type property.

Configure server directories

Deephaven server bootstrap configuration

The server reads its bootstrap configuration early in startup, before it reads any configuration file. Each bootstrap setting has a default value. To change one, set an environment variable or a system property. If both are set, the system property wins.

The server reads the deephaven.prop file from the config directory if that file exists. Otherwise, it reads the built-in dh-defaults.prop. To use a different file, set the Configuration.rootFile system property. For the full lookup order, see How to create a Deephaven configuration file.

Docker images set bootstrap values explicitly. The Deephaven Docker images run the production application with Docker-specific values, such as DEEPHAVEN_DATA_DIR=/data, DEEPHAVEN_CACHE_DIR=/cache, and DEEPHAVEN_CONFIG_DIR=/opt/deephaven/config.

Set directories for a single run

To set the data directory for a single run, use the DEEPHAVEN_DATA_DIR variable:

To set the cache or config directory, use DEEPHAVEN_CACHE_DIR or DEEPHAVEN_CONFIG_DIR the same way:

To set the same directory as a system property, pass it in START_OPTS:

OS-dependent directories

In these paths, <application> is the value of the Application name parameter (deephaven by default).

On Linux, if XDG_DATA_HOME, XDG_CACHE_HOME, or XDG_CONFIG_HOME is set, the matching directory uses that variable's value in place of $HOME/.local/share, $HOME/.cache, or $HOME/.config.

Related documentation

• How to configure the Docker application
• How to create a Deephaven configuration file
• Install and run the Deephaven production application
• Install Deephaven with Docker
• Configuration properties
• Periodic update graph configuration