Configuration properties reference

This guide shows how to set Deephaven Community configuration properties for Docker and the production application, then lists common properties by area.

How to set properties

Set a property in a configuration file, or pass it as a -D<property>=<value> JVM argument.

  • A -D argument overrides the same property in the configuration file.
  • If the file marks that property final, the -D argument causes a configuration error instead.

Use -D arguments for quick testing and a configuration file for production. The subsections below show where the file goes and how to pass -D arguments for each way of running the server.

Configuration file

Create a deephaven.prop file that sets your properties, and save it in the config directory, which defaults to the location in OS-dependent directories. For example:

Keep the includefiles=dh-defaults.prop line first. It loads the built-in defaults that the tables on this page list, and the server doesn't start without some of them. Deephaven configuration files describes how the server finds and layers configuration files.

Docker application

To configure the Docker application, mount your configuration file at /opt/deephaven/config/deephaven.prop. /opt/deephaven/config is the config directory that Docker image defaults lists. Set JVM options such as heap size in the START_OPTS environment variable, which the server's start script passes to the JVM as arguments:

The server-slim image doesn't include Python. Its own deephaven.prop sets deephaven.console.type=groovy, but your mounted file replaces it. Set deephaven.console.type=groovy in your file, as the configuration file example does. Otherwise, the server tries to start a Python console and fails.

For quick testing or a small number of properties, add -D arguments to START_OPTS as well. Each -D argument sets one property:

Don't change http.port in a Docker container, and set it back to 10000 if you turn on SSL. The server listens on port 10000 inside the container, and the Docker health check connects to that port, so Docker reports a container that listens on another port as unhealthy. To use a different host port, change only the host side of the ports mapping, as the complete example does.

Production application

The production application is the Deephaven server distributed as a tar archive and started with ./bin/start. Set its properties in a configuration file in the config directory, which defaults to the location in OS-dependent directories. Set JVM options, such as heap size, in START_OPTS. As with Docker, -D arguments in START_OPTS set individual properties for quick testing.

The production application starts a Python console by default. Set deephaven.console.type=groovy in your configuration file, as the configuration file example does, or with -D in START_OPTS:

JVM arguments

Pass these common JVM arguments in START_OPTS. For more about heap size, see Configure and adjust heap size.

ArgumentDescriptionExample
-XmxMaximum heap size-Xmx4g
-XmsInitial heap size-Xms2g

Bootstrap configuration

Deephaven reads bootstrap configuration at startup, before it reads any configuration file, so a configuration file can't set it. Set each value with its environment variable or as a -D JVM argument (a system property). If both are set, the system property wins.

SettingEnvironment variableSystem propertyDescriptionDefault
Application nameDEEPHAVEN_APPLICATIONdeephaven.applicationName used in the default data, cache, and config directory pathsdeephaven
Data directoryDEEPHAVEN_DATA_DIRdeephaven.dataDirDirectory where users and applications read and write dataOS-dependent
Cache directoryDEEPHAVEN_CACHE_DIRdeephaven.cacheDirDirectory where the server reads and writes cache dataOS-dependent
Config directoryDEEPHAVEN_CONFIG_DIRdeephaven.configDirDirectory where the server reads configuration filesOS-dependent
Quiet flagDEEPHAVEN_QUIETdeephaven.quietSuppress bootstrap loggingfalse

OS-dependent directories

When neither its environment variable nor its system property sets the data, cache, or config directory, Deephaven uses the default location for the operating system. In these paths, <application> is the application name from the table above, which defaults to deephaven.

OSData directoryCache directoryConfig 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>/

On Linux, if XDG_DATA_HOME, XDG_CACHE_HOME, or XDG_CONFIG_HOME is set, Deephaven uses that directory in place of $HOME/.local/share, $HOME/.cache, or $HOME/.config.

Docker image defaults

Docker images set the following environment variables by default. The first three set the bootstrap directories above:

  • DEEPHAVEN_DATA_DIR=/data
  • DEEPHAVEN_CACHE_DIR=/cache
  • DEEPHAVEN_CONFIG_DIR=/opt/deephaven/config
  • EXTRA_CLASSPATH=/apps/libs/*

EXTRA_CLASSPATH adds the JAR files in /apps/libs to the server's classpath.

Server configuration

These properties control the core server behavior.

PropertyDescriptionDefault
http.hostNetwork interface to bind to (IP address or hostname)All interfaces
http.portPort the server listens on. Defaults to 443 when ssl.identity.type is set, which turns on SSL.10000
http.targetUrlUser-accessible target URL (useful behind proxies)Auto-computed from host/port
http.session.durationMsSession duration in milliseconds300000 (5 minutes)
storage.pathRoot directory for the web UI's notebooks and layouts<deephaven.dataDir>/storage
deephaven.console.typeScript language for the server's console session: python or groovy. The language must be installed.python
grpc.maxInboundMessageSizeMaximum size in bytes of a gRPC message the server accepts from a client104857600 (100 MiB)
scheduler.poolSizeSize of the scheduler thread pool4
proxy.hintHint that the server runs behind a proxy. When true, http.websockets defaults to none and http.http1 defaults to false.Not set
shutdown.timeoutMsMilliseconds to wait for graceful shutdown10000

Session initialization scripts

The server doesn't read a configuration property for Groovy init scripts. To run a Groovy script when the server starts, use a script application.

Authentication configuration

These properties control how users authenticate to the server.

PropertyDescriptionDefault
AuthHandlersComma-separated list of authentication handler class namesio.deephaven.authentication.psk.PskAuthenticationHandler
authentication.pskPre-shared key value for PSK authenticationRandomly generated key
authentication.anonymous.warnLog a warning when anonymous authentication is enabledtrue
authentication.client.configuration.listComma-separated list of properties the server sends to clients before they log in. See the note below the table.AuthHandlers

The start script of the production application, which the Docker images also use, already sets authentication.client.configuration.list with -D, so a value in deephaven.prop has no effect there. Set it with -D in START_OPTS instead.

Available authentication handlers

The server includes these handlers:

Handler classDescription
io.deephaven.authentication.psk.PskAuthenticationHandlerPre-shared key (PSK) authentication (default)
io.deephaven.auth.AnonymousAuthenticationHandlerNo authentication required

Other authentication handlers require adding their provider JAR to the server's classpath (for example, /apps/libs in the Docker images). Each guide shows how:

Handler classDescription
io.deephaven.authentication.mtls.MTlsAuthenticationHandlerMutual TLS (mTLS) authentication
io.deephaven.authentication.oidc.OidcAuthenticationHandlerKeycloak/OIDC authentication
io.deephaven.authentication.sql.BasicSqlAuthenticationHandlerSQL-backed username/password authentication

HTTP server configuration

These properties configure the server's HTTP, HTTP/2, and WebSocket transport.

PropertyDescriptionDefault
http.websocketsWebSocket support mode: none, grpc-websockets, grpc-websockets-multiplex, both. Defaults to none when ssl.identity.type turns on SSL or proxy.hint is true.both
http.http1Enable HTTP/1.1 support. Defaults to false when proxy.hint is true.true
http.compressionEnable HTTP compressiontrue
https.sniHostCheckReject HTTPS requests whose Host header doesn't match the server certificate (SNI host check)true
http.requireHttp2Reject gRPC calls that are not made over HTTP/2true
http2.stream.idleTimeoutMsHTTP/2 stream idle timeout in milliseconds. 0 or a negative value disables it.0
http2.maxConcurrentStreamsMaximum concurrent HTTP/2 streams. The default comes from Jetty.128
http.maxHeaderRequestSizeMaximum HTTP header size in bytes. The default comes from Jetty.8192
http.allowedMethodsAllowed HTTP methods (comma-separated)GET,POST,OPTIONS

SSL/TLS configuration

Configure SSL with these properties, in a configuration file or as -D arguments. Setting ssl.identity.type turns on SSL. None of these properties is set by default.

Turning on SSL also changes the default http.port from 10000 to 443. In a Docker container, set http.port=10000 so the ports mapping still reaches the server. The image's health check connects without TLS, so Docker reports an SSL-enabled container as unhealthy even when the server runs normally. See mTLS authentication for detailed examples.

PropertyDescription
ssl.identity.typeIdentity type. Only privatekey is supported.
ssl.identity.certChainPathPath to the certificate chain (required when ssl.identity.type is set)
ssl.identity.privateKeyPathPath to the private key (required when ssl.identity.type is set)
ssl.trust.typeTrust type. Only certs is supported.
ssl.trust.pathPath to trust certificates (required when ssl.trust.type is set)
ssl.clientAuthenticationClient auth mode: NONE, WANTED, NEEDED
outbound.ssl.*Outbound SSL configuration. Takes the same suffixes as the ssl.* properties in this table, such as outbound.ssl.trust.type.

Security headers

These properties configure HTTP security headers for production deployments. Each header has an .enabled and a .value property, and the server sends a header only when its .enabled property is true and its .value property is set. The table lists the headers that dh-defaults.prop defines. To send another response header, set http.add.header.<Header-Name>.enabled=true and http.add.header.<Header-Name>.value.

Turn on Strict-Transport-Security only after TLS is deployed and working. Browsers remember the header for its max-age (one year by default), so turning it off later doesn't reach clients that already received it.

HeaderEnabled propertyValue propertyDefault enabledDefault value
Strict-Transport-Securityhttp.add.header.Strict-Transport-Security.enabledhttp.add.header.Strict-Transport-Security.valuefalsemax-age=31536000; includeSubDomains
X-Frame-Optionshttp.add.header.X-Frame-Options.enabledhttp.add.header.X-Frame-Options.valuefalseDENY
Content-Security-Policyhttp.add.header.Content-Security-Policy.enabledhttp.add.header.Content-Security-Policy.valuefalseframe-ancestors 'none';
X-XSS-Protectionhttp.add.header.X-XSS-Protection.enabledhttp.add.header.X-XSS-Protection.valuetrue1; mode=block
X-Content-Type-Optionshttp.add.header.X-Content-Type-Options.enabledhttp.add.header.X-Content-Type-Options.valuetruenosniff
Referrer-Policyhttp.add.header.Referrer-Policy.enabledhttp.add.header.Referrer-Policy.valuetrueno-referrer
Cross-Origin-Resource-Policyhttp.add.header.Cross-Origin-Resource-Policy.enabledhttp.add.header.Cross-Origin-Resource-Policy.valuetruesame-origin
Cross-Origin-Embedder-Policyhttp.add.header.Cross-Origin-Embedder-Policy.enabledhttp.add.header.Cross-Origin-Embedder-Policy.valuetruerequire-corp
Cross-Origin-Opener-Policyhttp.add.header.Cross-Origin-Opener-Policy.enabledhttp.add.header.Cross-Origin-Opener-Policy.valuetruesame-origin

Web UI configuration

These properties configure the Deephaven web UI defaults.

PropertyDescriptionDefault
web.storage.layout.directorySubdirectory of storage.path that the server creates at startup for layouts. The web UI always uses /layouts./layouts
web.storage.notebook.directorySubdirectory of storage.path that the server creates at startup for notebooks. The web UI always uses /notebooks./notebooks
web.webglEnable WebGL support in the web UItrue
web.webgl.editableAllow users to toggle the WebGL settingtrue
web.flattenViewportsFlatten each table before the web UI subscribes to the rows it displaysfalse

Formula validation

These properties configure validation of the query formulas that clients send over gRPC. See Formula validation configuration for details.

PropertyDescriptionDefault
ColumnExpressionValidatorValidator type: parsed or method_nameparsed
ColumnExpressionValidator.allowedMethods.*Used by the parsed validator. Patterns that name the methods that formulas may call. See Formula validation configuration for the pattern syntax.Set in dh-defaults.prop
ColumnExpressionValidator.annotationSets.*Used by the parsed validator. Annotation sets of methods that formulas may call. The server combines the values of every property with this prefix. ColumnExpressionValidator.annotationSets.default sets the default value.base,vector,function_library

Engine configuration

These properties configure the query engine: its update cycle, calendar and time zone, and performance monitoring. The Periodic Update Graph recomputes ticking tables in repeating refresh cycles. Its guide explains how the cycle duration affects updates.

PropertyDescriptionDefault
PeriodicUpdateGraph.targetCycleDurationMillisTarget cycle duration for the Periodic Update Graph in milliseconds1000

Calendar and time zone

These properties set the default business calendar, the calendars the server loads at startup, and the time zone aliases the server recognizes. To load your own calendars, see Work with calendars.

PropertyDescriptionDefault
Calendar.defaultDefault business calendarUTC
Calendar.importPathClasspath location of the list of built-in calendars. To add calendars, use Calendar.userImportPath./default_calendar_imports.txt
Calendar.userImportPathClasspath location of a list of extra calendars to load at startupNot set
timezone.aliasesFile path or classpath location of the time zone alias definitions/default_time_zone_aliases.csv

Performance monitoring

This property sets how often the server writes update performance reports to the performance tables.

PropertyDescriptionDefault
UpdatePerformanceTracker.reportIntervalMillisPerformance report interval in milliseconds60000

Complete example

This example shows a Docker Compose configuration with several customizations. The server listens on port 10000 inside the container, and the 8080:10000 mapping makes it reachable on host port 8080. It also mounts ./data at /data, the data directory, so notebooks, layouts, and other data persist on the host.

The mounted ./config/deephaven.prop file contains: