---
title: Configure the Deephaven production application
sidebar_label: Production application
---

This guide provides low-level details 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](https://github.com/deephaven/deephaven-core/releases), listed under assets.

The production application offers a greater degree of control and performance than other methods, 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 [Deephaven's Docker images](./docker-application.md).

This guide assumes familiarity with installing and running the Deephaven production application. For an introductory guide on installing and running, see [Install and run Deephaven with pre-built artifacts](../../tutorials/production-application.md).

## Prerequisites

Only Java is required to run the Deephaven production application. Deephaven recommends using the latest LTS version of Java. Java 11 or later is required.

The production application also requires Linux or Mac OS. Running on Windows requires Windows Subsystem for Linux (WSL)[<sup>[1]</sup>](#footnotes).

## Production application configuration

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

- `bin/`: Contains a [`start` script](../../tutorials/production-application.md#run-the-server) used to launch the server.
- `lib/`: Contains all of the JAR files that form the application classpath.
- `etc/` [<sup>[2]</sup>](#footnotes): Contains extra files that may be useful for configuring the server JVM.

### Environment variables

The [`start` script](../../tutorials/production-application.md#run-the-server) contains the logic to collect the arguments, assemble the classpath, and execute the `java` command to run the server. There are several environment variables that influence the [`start` script](../../tutorials/production-application.md#run-the-server):

| 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/*`                               |

## What the start script does

The end result of the [`start` script](../../tutorials/production-application.md#run-the-server) is a command that looks something like:

```shell
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_OPTS` are JVM arguments that can be overridden, but it is not recommended to set them.
- `START_OPTS` are additional JVM arguments that the user can set. It's recommended to set these over `JAVA_OPTS`.
- `<classpath>` is the constructed classpath. It cannot be changed, however, classpaths can be added with the `EXTRA_CLASSPATH` environment variable.
- `[optional-bootstrap-file]` is an optional file with properties that will take precedent over other system properties. This option may be removed in a future release.

### Deephaven server bootstrap configuration

Bootstrap configuration parameters are ones that get 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 either an environment variable or system property.

> [!NOTE]
> 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](./docker-application.md).

## 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](https://docs.gradle.org/current/userguide/application_plugin.html).

## Related documentation

- [How to configure the Docker application](./docker-application.md)
- [How to create a Deephaven configuration file](./config-file.md)
- [Build from source](../launch-build.md)
- [Install and run the Deephaven production application](../../tutorials/production-application.md)