Automate configuration with the Deephaven Updater

This guide explains how to set up and run the DeephavenUpdater tool to synchronize JARs, properties files, and trust certificates from a Deephaven server to any remote system that needs to connect to Deephaven services. This includes remote headless systems such as loggers, tailers, and development environments, as well as Swing desktop clients. Files are served by the Client Update Service (CUS), which runs as part of the Web API Service on the infra node.

Find the Client Update Service URL

The CUS runs on the infra node as the web_api_service. Default ports are:

  • 8123 — Web API service general port
  • 8443 — CUS listener port (HTTPS, when a TLS keystore is configured)
  • 8480 — CUS listener port (HTTP, when no TLS keystore is configured)
  • 8000 — When Deephaven is configured to use Envoy

You can download the Deephaven Launcher (which includes the Updater) from one of these URLs:

  • https://deephaven-infra-server.mycompany.net:8123/launcher
  • https://deephaven-infra-server.mycompany.net:8443/launcher (HTTPS)
  • http://deephaven-infra-server.mycompany.net:8480/launcher (HTTP, no TLS)
  • https://deephaven-envoy-server.mycompany.net:8000/launcher

Replace the hostnames with the appropriate nodes in your Deephaven cluster.

You can also download the Deephaven Launcher directly from JFrog:

  • https://illumon.jfrog.io/ui/repos/tree/General/lib-custom-local/io/deephaven/launcher

The appbase URL used by the launcher or updater is determined by the client_update_service.host and client_update_service.port properties, and typically defaults to one of the following (see Client Update Service for port override options):

  • https://deephaven-infra-server.mycompany.net:8443/iris/ (HTTPS)
  • http://deephaven-infra-server.mycompany.net:8480/iris/ (HTTP, no TLS)
  • https://deephaven-envoy-server.mycompany.net:8000/iris/

Linux and macOS

This section covers setup for headless Linux and macOS systems, such as remote loggers, tailers, and development environments.

Install the Deephaven Updater

Download the Deephaven Launcher .tgz file from the Client Update Service URL. The filename includes the Deephaven version — use the version that matches your server installation. This installation is required only once per system. The example below installs into /home/mytaileraccount; use any directory appropriate for your environment:

Create an instance and sync files

Run the updater with the instance name and the CUS URL to create an instance and download client files:

Deephaven is a friendly name for this instance. Any name without spaces or special characters is easier to use in scripts.

Keep files up to date

To update binaries and configuration files at a later time, omit the URL:

Re-run this command periodically — or before each process startup — to ensure this system has the latest binaries and configuration from the Deephaven server.

Windows

Install the Deephaven Updater

Download the Deephaven Launcher installer from the Client Update Service URL. The filename includes the Deephaven version — use the version that matches your server installation. Run it silently with the /S option:

The Deephaven Launcher installs to one of the following locations:

Create an instance and sync files

Run one of these commands in a cmd window to create an instance, replacing the URL with your Client Update Service URL and using the path that matches your install location:

Keep files up to date

To update at a later time, omit the URL:

Run a client process

After syncing files with the Updater, use the downloaded JARs and configuration to launch a headless Deephaven process (such as a tailer) or the Deephaven Swing console. Replace [instance_name], [service_name], and [key file] with actual values for your environment.

Linux and macOS

Windows

Customizing locations

The Deephaven Updater reads properties from several locations, where HOME is the current user's home directory and INSTALLDIR is where the Deephaven Updater script is installed. Direct command-line arguments take precedence over properties files. Properties files are listed below from highest to lowest priority:

  • HOME/.illumon.launcher.properties
  • /etc/illumon.launcher.properties (non-Windows)
  • $PROGRAMDATA/illumon/illumon.launcher.properties (Windows)
  • INSTALLDIR/illumon/illumon.launcher.properties (Windows)
  • INSTALLDIR/lib/illumon.launcher.properties

Settings

Change the default location for downloaded program files and workspace files by setting these properties in any of the files above:

  • IrisConfigurationLauncher.instanceRoot=${user.home}/iris/.programfiles
  • IrisConfigurationLauncher.workspaceRoot=${user.home}/iris/workspaces

See INSTALLDIR/lib/illumon.launcher.properties for additional properties and default values.

The DeephavenUpdater script also accepts command line parameters for setting these locations:

Caution

If you change the locations on the command line, you must always include the same command line parameters on every invocation, or the updater will not find previously downloaded program files.

Troubleshooting

The Deephaven Updater prints its log to stdout. This log contains connection and certificate details and is the primary tool for diagnosing configuration issues. Deephaven support requires this information to help troubleshoot.

If the certificates used by the Deephaven server are not trusted by your client, add --insecure to allow the server's trust store files to be downloaded. The updater then uses these files for subsequent connections, and any client can use them for TLS validation.

The following properties increase logging detail (set them in any file listed in Customizing locations):

  • IrisConfigurationLauncher.connectionTimeoutMs — Change the timeout used when attempting to connect to the server.
  • IrisConfigurationLauncher.verboseLogging=true — Verbose logging adds more detail about progress and full exception text.
  • javax.net.debug=all — Adds very verbose logging about certificates and TLS negotiations.