Configure the Deephaven production application
This guide provides detailed information about the Deephaven production application bootstrap configuration and startup process. The Deephaven production application is the recommended way to run Deephaven for any production application, hence its name. It runs Deephaven directly from artifacts produced during each new release. These artifacts can be found in the GitHub releases page, listed under assets.
The production application offers a greater degree of control and performance than other methods. However, it 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 or pip-installed Deephaven.
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
| Package | Recommended version | Required version |
|---|---|---|
| java | latest LTS | >= 11 |
| python | >=3.10 | >= 3.8 |
The production application also requires Linux or Mac OS. Running on Windows requires Windows Subsystem for Linux (WSL)[1].
Production application configuration
The inner structure of the application is a root directory of the form server-jetty-<version>/ with further subdirectories:
bin/: Contains astartscript used to launch the server.lib/: Contains all of the JAR files that form the application classpath.etc/[2]: Contains extra files that may be useful for configuring the server JVM.
Environment variables
The start script contains the logic to collect the arguments, assemble the classpath, and execute the java command to run the server. Several environment variables influence the start script:
| Environment Variable | Description | Default Value | Example |
|---|---|---|---|
JAVA_OPTS | The main JVM arguments. These are generated by the start script, but can be overridden. | Deephaven-recommended arguments and property definitions. | N/A. It is not recommended to set JAVA_OPTS. |
START_OPTS | Additional user-supplied JVM arguments. These are added to the command line after JAVA_OPTS. | None | START_OPTS="-Xms4g -Xmx4g -Dmyproperty=myvalue -Ddeephaven.console.type=groovy" |
EXTRA_CLASSPATH | Additional directories to include in the Java classpath (e.g., /apps/libs/*) | None | EXTRA_CLASSPATH="/apps/libs/*:/opt/my_java_libs/* |
VIRTUAL_ENV | The Python virtual environment to use. | None | VIRTUAL_ENV="/path/to/my/venv" |
What the start script does
The start script executes a shell command that looks something like:
java <required-opts> $JAVA_OPTS $START_OPTS -classpath <classpath> io.deephaven.server.jetty.JettyMain [optional-bootstrap-file]
<required-opts>are pre-defined JVM settings that cannot be changed. Deephaven requires these settings.JAVA_OPTSare JVM arguments that can be overridden, but it is not recommended to set them.START_OPTSare additional JVM arguments that the user can set. It's recommended to set these overJAVA_OPTS.<classpath>is the constructed classpath. It cannot be changed, however, classpaths can be added with theEXTRA_CLASSPATHenvironment variable.[optional-bootstrap-file]is an optional file with properties that takes precedence over other system properties. This option may be removed in a future release.
Deephaven server bootstrap configuration
Bootstrap configuration parameters are set early in the application startup lifecycle, before anything in a configuration file. The Deephaven server process has a few essential bootstrap configuration parameters. They have default values that the user may choose to change via an environment variable or system property.
Bootstrapping configuration is limited in scope and is a prerequisite to the Deephaven configuration file.
| Bootstrap configuration parameter | Environment variable | System property | Description | Default value |
|---|---|---|---|---|
| Application name | DEEPHAVEN_APPLICATION | deephaven.application | The name used to inform default values for other pieces of configuration | deephaven |
| Data directory | DEEPHAVEN_DATA_DIR | deephaven.dataDir | The directory where users and applications read and write data | OS-dependent |
| Cache directory | DEEPHAVEN_CACHE_DIR | deephaven.cacheDir | The directory where the Deephaven server reads and writes cache data | OS-dependent |
| Config directory | DEEPHAVEN_CONFIG_DIR | deephaven.configDir | The directory where the Deephaven server reads configuration files | OS-dependent |
| Quiet flag | DEEPHAVEN_QUIET | deephaven.quiet | Whether to suppress bootstrap logging | false |
OS-dependent directories
| OS | Data directory | Cache directory | Config directory |
|---|---|---|---|
| Linux | $HOME/.local/share/<application>/ | $HOME/.cache/<application>/ | $HOME/.config/<application>/ |
| macOS | $HOME/Library/Application Support/io.Deephaven-Data-Labs.<application>/ | $HOME/Library/Caches/io.Deephaven-Data-Labs.<application>/ | $HOME/Library/Application Support/io.Deephaven-Data-Labs.<application>/ |
Downstream uses of the production application
Docker images
The Deephaven Docker images are based on the production application, as described above, with Docker-specific bootstrap values. For example, the images set the environment variables DEEPHAVEN_DATA_DIR=/data, DEEPHAVEN_CACHE_DIR=/cache, and DEEPHAVEN_CONFIG_DIR=/opt/deephaven/config.
For more information, see the Docker application documentation.
Python-embedded server
The Deephaven Python embedded server is a PyPi package that includes all the logic to start up the Deephaven server directly from Python. It does not use the production application start script, but it does use the same default configuration parameters.
Footnotes
1: Windows native support may be possible in the future.
2: For those interested in the nitty gritty, check out the Gradle application plugin.