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.shand 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:
- The first stage uses the
web-plugin-packagerimage to download plugins from npm. - 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.
-
Create a directory for your deployment and save the following as
Dockerfilein it: -
Build the image and run it:
For more
docker runoptions, see Configure the Deephaven Docker application.If you use Docker Compose, save the following as
docker-compose.ymlin the same directory. It builds the image from your Dockerfile rather than pulling one from the registry:Then run
docker compose up --buildinstead of the twodockercommands. -
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. -
Open the IDE at
http://localhost:10000/ideand 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:
deephaven-java-client-sessionif you create aSessiondirectly.deephaven-java-client-barrage-daggerif you already use aBarrageSessionfor table data, as in Connect to the server.
The following example adds the session library:
The examples below assume a connected Session in a variable named session. To get one:
- With only the session library, create a
Sessionfrom aSessionFactoryConfig, as the Java client session examples do. - With a
BarrageSession, as in Connect to the server, call itssessionmethod, which it inherits fromFlightSession.
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:
- You supply a
MessageStream<ServerData>that receives messages from the server. - You send messages through the
MessageStream<ClientData>thatconnectreturns.
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:
deephaven-plugin-ui: A plugin for building real-time dashboards with deephaven.ui.deephaven-plugin-plotly-express: A plugin, Deephaven Express, that makes Plotly Express compatible with Deephaven tables.deephaven-plugin-matplotlib: A plugin that makes Matplotlib and Seaborn compatible with Deephaven tables.
Authentication
Authentication plugins have a more complex installation process than other plugins. See the following guides for details:
- Keycloak: A plugin that enables the use of Keycloak and OpenID Connect (OIDC) for authentication.
- mTLS: A plugin that enables mutual TLS (mTLS) authentication.
- Username/password: A plugin that enables username/password authentication.
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, whichpydeephavenremoved in version 0.37.0, so it needs updating before it runs with current clients. It uses Python'spicklemodule, 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, whichpydeephavenremoved 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:
- For a fetch-only plugin, and how a bidirectional plugin differs from one, see Create your own plugin.
- For a complete bidirectional plugin, see the Python version of Create your own plugin.
- To use a plugin object from Java, see Use plugins from the Java client.
Related documentation
- Build and launch Deephaven from source code
- Configure and use pre-shared key authentication
- Configure JS plugins
- Configure Keycloak for authentication
- Configure mTLS for Deephaven
- Configure the Deephaven Docker application
- Configure username/password authentication
- Create your own plugin
- Extract data with a Java client
- Install and use Java packages
- Install packages
- Launch Deephaven from pre-built images
- Python client quickstart
BarrageSessionJavadocClientDataJavadocFlightSessionJavadocObjectServiceJavadocObjectType.MessageStreamJavadocObjectTypeBaseJavadocScopeIdJavadocServerDataJavadocSessionJavadocSessionFactoryConfigJavadocTypedTicketJavadoc