Install and use plugins

This guide covers how to install and use pre-built plugins in Deephaven. A plugin extends the functionality of Deephaven, much as a Java library extends what Groovy and Java code can do. A plugin's server-side components are often packaged as Java libraries, but not every Java library is a plugin. Plugins in Deephaven can extend the functionality of a running server, UI, client API, or all of them.

Deephaven offers several pre-built plugins that extend the platform's functionality, and anyone using Deephaven Community Core can install them. For the plugins you can install, see Available plugins.

Note

To install Linux system packages rather than plugins, see Install packages. To add Java libraries to the server, see Install and use Java packages.

To have complete control of the build process, see Build and launch Deephaven from source code.

For information on building your own plugins, see Create your own plugin.

Types of plugins

Deephaven plugins come in four types:

  • Server-side plugins extend the Deephaven server. For example, authentication plugins add authentication methods such as mutual TLS (mTLS). Some server-side plugins, such as the plotting plugins for Deephaven Express and Matplotlib, are Python packages that run only on a server with Python as its scripting language.
  • UI plugins, also called JavaScript (JS) plugins, extend the Deephaven web IDE. They are JavaScript packages that the server loads and serves to the browser. For example, the theme pack adds IDE color themes.
  • Client-side plugins extend Deephaven's client APIs. For example, a plugin can extend the Python client so it can work with a plugin's objects on the server. The Java client API doesn't load plugins, but it can fetch plugin objects from the server and exchange messages with them in a format the plugin defines. See Use plugins from the Java client.
  • Bidirectional plugins keep a message stream open between a server-side object and a client so that the two can exchange messages. Some, like the Python examples in Bidirectional plugin examples, also ship a client-side plugin. The Java client can talk to a bidirectional plugin directly.

Install a plugin

Note

Authentication plugins need additional configuration. See Authentication for the guide to each one.

On a Groovy server, how you install a plugin depends on how it is packaged:

  • Server-side components are Java libraries on the server's classpath. To add them, see Install and use Java packages.
  • JS components published to npm need packaging. Package them with pack-plugins.sh and copy the result to the directory where the server looks for JS plugins. In Docker, build a custom image, as described in the next section. For other installations, see Configure JS plugins.

The server loads plugins only when it starts, so restart the server after you install a plugin.

Extend Docker images for JS plugins

First, follow the steps in Launch Deephaven from pre-built images.

The server-slim image runs a Groovy console. To add JS plugins to it, build a custom image in two stages:

  1. The first stage uses the web-plugin-packager image to download plugins from npm.
  2. The second stage copies them into server-slim.

Each plugin's npm package name is the name field of src/js/package.json in its folder of the plugins repository. You can also search npm for the deephaven-js-plugin keyword.

The following Dockerfile is the general template:

Replace <plugins> with one or more npm package names, separated by spaces. To pin a version, append @<version> to a name.

For more about JS plugin packaging and configuration, see Configure JS plugins.

Example: install the theme pack

The theme pack plugin adds UI themes such as Dracula, Night Owl, and Solarized Dark to the Deephaven IDE. The theme pack has no server-side logic. Its npm package, @deephaven/js-plugin-theme-pack, needs no Python package, so a Groovy server can use it.

  1. Create a directory for your deployment and save the following as Dockerfile in it:

  2. Build the image and run it:

    For more docker run options, see Configure the Deephaven Docker application.

    If you use Docker Compose, save the following as docker-compose.yml in the same directory. It builds the image from your Dockerfile rather than pulling one from the registry:

    Then run docker compose up --build instead of the two docker commands.

  3. Confirm that the server loaded the plugin. The server lists its JS plugins at http://localhost:10000/js-plugins/manifest.json:

    The output includes @deephaven/js-plugin-theme-pack.

  4. Open the IDE at http://localhost:10000/ide and log in with the pre-shared key printed in the server log. Then click the gear icon at the top right of the IDE to open the Settings menu. Expand the Theme section and pick one of the added themes from the Pick a color scheme list.

Use plugins from the Java client

The Java client can interact with plugin objects on the server through the fetchable and bidirectional methods of a Session. Each method takes a typed ticket, which pairs the plugin's object type with a reference to the object, such as a variable name in the server's scope.

Set up the Java client

To use the Java client in your project, add one client library to your build.gradle, replacing <version> with your Deephaven version:

The following example adds the session library:

The examples below assume a connected Session in a variable named session. To get one:

Fetch a plugin object

For plugins that send their object's contents to the client, use fetchable:

Work with bidirectional plugins

For bidirectional plugins, use bidirectional to open a message stream to the object. This example reuses the typedTicket created in Fetch a plugin object. The stream has two directions:

The following example opens a stream, sends one message, and prints the size of each message the server sends back:

For a complete example, see MessageStreamSendReceive.java.

Available plugins

The plugins repository

Deephaven hosts a plugins repository that contains many of the official plugins offered. It's a good place to find more information about the plugins and view their source code.

Note

Some plugins are not in the plugins repository but are still available for use. For instance, some authentication plugins are JAR files only available on Maven Central.

Two folders in the plugins repository are of particular interest:

  • plugins: Contains the implementation of the plugins. This is where you can find each plugin's source code and additional documentation.
  • templates: Contains templates for creating new plugins. This is a great starting point if you want to create your own plugin.

The following sections group some of the available plugins by functionality.

User interface

The theme pack has no server-side logic, so a Groovy server can use its npm package. See Example: install the theme pack.

The following user interface plugins are Python packages for servers with Python as their scripting language. The ghcr.io/deephaven/server image already includes them, but the Groovy server-slim image can't use them:

Authentication

Authentication plugins have a more complex installation process than other plugins. See the following guides for details:

Bidirectional plugin examples

Bidirectional plugins let you define custom remote procedure call (RPC) methods that clients call to interact with objects on a running server and get objects back. The following examples are Python plugins, with a Python server plugin and a Python client plugin:

  • Pickle RPC plugin: A plugin to remotely execute methods on a Deephaven server. Its client code imports pydeephaven.experimental.server_object, which pydeephaven removed in version 0.37.0, so it needs updating before it runs with current clients. It uses Python's pickle module, which is not secure. Read its README before you adapt it.
  • Example bidirectional plugin: A minimal bidirectional plugin and a client that uses it. Its client code imports pydeephaven.experimental.server_object, which pydeephaven removed in version 0.37.0. For client code that works with current versions, see the Python version of Create your own plugin.

A Groovy server can also host bidirectional plugins written in Java or Groovy. Such a plugin extends ObjectTypeBase and implements its compatibleClientConnection method to return a MessageStream. To learn more: