Skip to main content
Version: Java (Groovy)

Use Application Mode scripts

Deephaven's Application Mode allows you to initialize server state. This guide covers how to use Application Mode scripts, allowing users to run Python or Groovy code when Deephaven is launched.

Application Mode scripts are defined by having type=script set in the Application Mode *.app config file. Once defined, any Python or Groovy scripts in the file_N settings of the config file will run when Deephaven is launched.

Deephaven's deephaven-examples Github organization contains many examples of applications that use Application Mode. Specific tutorial examples can also be found for Groovy and Python.

Application Mode config file​

Deephaven expects your Application Mode configuration to be defined in a config file that ends with .app (this is the *.app file). For using Application Mode with scripts, you need to set:

  • type=script
  • the scriptType to python or groovy
  • your file_N files to run. Your file_N files can be any number of files defined relative to where the *.app file is located when packaged into Docker.

The following shows an example of a typical .app file:

type=script
scriptType=python
enabled=true
id=hello.world
name=Hello World!
file_0=./helloWorld.py

Application Mode config files directory​

In your docker-compose.yml file in the grpc-api section, the -Ddeephaven.application.dir flag is set to the directory containing the *.app Application Mode files. Since this runs in Docker, this value will need to be wherever you decide to package your directory.

The following shows an example of what your grpc-api section may look like.

grpc-api:
  image: my-app/deephaven-grpc:latest
  expose:
    - '8080'
  volumes:
    - ./data:/data
    - api-cache:/cache
  environment:
    - JAVA_TOOL_OPTIONS=-Xmx4g -Ddeephaven.console.type=python -Ddeephaven.application.dir=/app.d

Packaging your files​

Although Deephaven doesn't have strict rules on where your *.app config files and your script files are located, it may be easier to put them in the same directory. This will simplify packaging your files with Docker, and will simplify your file_N paths in your *.app config file.

In this example, we will show what a directory app.d will look like, and how to package it with a Deephaven Dockerfile.

app.d directory​

Let's say we have two Python scripts (init_tables.py and functions.py) we want to run when Deephaven is launched. We can make a directory called app.d, and put these scripts in there.

app.d
  init_tables.py
  functions.py

Now we need to define our *.app config file to run these Python scripts on launch. Let's name it config.app and use the following to define it.

type=script
scriptType=python
enabled=true
id=app-mode-init
name=App Mode Init
file_0=./init_tables.py
file_1=./functions.py

Once we put our config.app file in our app.d directory, it will look like this.

app.d
  init_tables.py
  functions.py
  config.app

Dockerfile​

Since we have bundled our scripts and config files in the same directory (app.d), our Dockerfile simply just needs to copy over this directory when we build it. All we need to do is make our own Dockerfile that extends the Deephaven base ghcr.io/deephaven/grpc-api image, and copies over our app.d directory.

This Dockerfile assumes that it is in the same directory as app.d.

FROM ghcr.io/deephaven/grpc-api
COPY app.d /app.d

Because you're now extending Deephaven's Docker image, you will need to build this locally and tag it with an appropriate tag. You will also need to reference this tag in your docker-compose.yml file.

docker build --tag my-app/deephaven-grpc .

Putting it all together​

Once we've defined our files, our directory should look like this.

my-project
  Dockerfile
  docker-compose.yml
  app.d
    init_tables.py
    functions.py
    config.app

Our Dockerfile should contain the following.

FROM ghcr.io/deephaven/grpc-api
COPY app.d /app.d

Assuming we build and tag our Docker image with docker build --tag my-app/deephaven-grpc ., the grpc-api section of our docker-compose.yml file should look like this.

grpc-api:
  image: my-app/deephaven-grpc:latest
  expose:
    - '8080'
  volumes:
    - ./data:/data
    - api-cache:/cache
  environment:
    - JAVA_TOOL_OPTIONS=-Xmx4g -Ddeephaven.console.type=python -Ddeephaven.application.dir=/app.d

After building the Docker image, we can now launch the application by running docker compose up.

Example scripts​

This section contains examples of code that can be included in a Groovy script. When configured, this code will run when Deephaven is launched.

hello = { ->
    println "Hello world"
}

source = emptyTable(5)
result = source.update("Values = i")