---
title: Configure the Deephaven production application
sidebar_label: 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](https://github.com/deephaven/deephaven-core/releases), 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](../../getting-started/docker-install.md) or [pip-installed](../../getting-started/pip-install.md) 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](../../getting-started/production-application.md).

## 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 v2 (WSL 2)[<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](../../getting-started/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](../../getting-started/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. Several environment variables influence the [`start` script](../../getting-started/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/*`                               |
| `VIRTUAL_ENV`        | The Python virtual environment to use.                                                         | None                                                      | `VIRTUAL_ENV="/path/to/my/venv"`                                                  |

### What the start script does

The [`start` script](../../getting-started/production-application.md#run-the-server) executes a shell 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 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.

> [!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).

### Python-embedded server

The [Deephaven Python embedded server](https://pypi.org/project/deephaven-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](../../getting-started/production-application.md#run-the-server), but it does use the same [default configuration parameters](#deephaven-server-bootstrap-configuration).

## 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)
- [Install and run the Deephaven production application](../../getting-started/production-application.md)
- [Build from source](../../getting-started/launch-build.md)