Deephaven Launcher and Client configuration

Client Components Update

When the Deephaven Launcher starts a console instance, it verifies that the instance has the latest versions of JAR files and other files from the Client Update Service (CUS) associated with the instance. It will download newer files if updates are available.

Once the console is running, it will check for changes every 10 minutes. If new files are found (because an update has been applied or a configuration file changed on the server), a message banner will appear on the client console to inform the user that the console is out of date. A relaunch of the console will then be required to download and apply the new files.

Continuing to run the console with out of date components may appear to work fine, but problems may arise when client-side settings are not correct for the current environment or when the client is using classes that no longer match the versions installed on the server.

When the Web API Service starts or receives a reload request, it synchronizes system files and configuration into a temporary directory (e.g., /tmp/cus7948278661189215940/). A digest file is created that the launcher uses to avoid re-downloading unchanged files. The files in this temporary directory should never be edited.

The getdown.txt file in this temporary directory controls most of the Client Update Service behavior. This file is dynamically built by the Client Update Service when it starts and when it reloads, using several files and properties.

• A system-owned /etc/sysconfig/illumon.d/client_update_service/iris/iris/getdown.txt.pre contains values maintained by Deephaven, and is automatically replaced every time Deephaven is upgraded.
• A customer-owned /etc/sysconfig/illumon.d/client_update_service/getdown.global, which is where all customer-controlled configuration should be placed. This file is created with default values during initial system installation but never replaced during upgrades.
• Customer-owned /etc/sysconfig/illumon.d/client_update_service/getdown.java.11 and /etc/sysconfig/illumon.d/client_update_service/getdown.java.17 files which contain default JVM parameters that will be use by clients based on the Java installation used.

Customer-updatable values are used to generate the getdown.txt file, which is uploaded to clients. These values are described below.

Further information on the above files is provided in the Client Update Service documentation.

Customer-updatable values

This section describes how important values are generated for the getdown.txt file provided by the Client Update Service. You can see the generated file in a browser using a URL like https://<fqdn>:8123/iris/getdown.txt, or https://<fqdn>:8000/iris/getdown.txt if Envoy is being used.

When any of the files needed by the client are updated, you must reload the Client Update Service (for getdown file changes) or restart the Web API Service (for certain property changes) to regenerate the configuration files and digest. The Web API Service is restarted automatically after a Deephaven product RPM is applied to a query server.

Base application URL

getdown.txt includes an appbase entry which indicates the URL from which all subsequent files will be downloaded. All other files are relative to this root. This is generated by the web API service (running the Client Update Service) as follows.

• The protocol of the Web API Service (http vs https) determines the http or https prefix. In most configurations this will be https.
• The property client_update_service.host defines the host name. This property must be defined, and is automatically set in iris-endpoints.prop by the installer.
• The port number depends on several properties and configuration values.
  • If the property Webapi.server.cus.getdown.port is defined, the port is taken from that.
  • If Envoy is not being used, the property client_update_service.port defines the port.
  • Or, if Envoy is being used:
    • If the envoy.front.proxy.url property is defined, the port is taken from that.
    • Otherwise, a default port of 8000 is used.

For example, if the properties client_update_service.host=deephaven-infra-server.mycompany.net and Webapi.server.cus.getdown.port=8443 are set in a non-Envoy configuration, appbase will be set to:

appbase = https://deephaven-infra-server.mycompany.net:8443/iris/

The appbase entry in /etc/sysconfig/illumon.d/client_update_service/getdown.global is not used. It will be replaced with a value calculated as described above.

If you change the properties used to calculate appbase, you must restart the Web API Service.

Launcher title bar

The name displayed by the Deephaven launcher's title bar is set by ui.name in /etc/sysconfig/illumon.d/client_update_service/getdown.global. The default value is ui.name = Deephaven.

For example:

ui.name = Company Name Here

After changing this value, reload the Client Update Service.

Configuration file

The root properties file is set by the Configuration.rootFile jvmarg value in /etc/sysconfig/illumon.d/client_update_service/getdown.global. The default is iris-common.prop and this should be changed with caution.

jvmarg = -DConfiguration.rootFile=iris-common.prop

After changing this value, reload the Client Update Service.

Non-Updatable values

The following values cannot be edited.

Java version

The Java version running on a Deephaven server is found in the file /usr/illumon/latest/etc/JAVA_VERSION. This value is used to select one of the getdown.java.<version> files from /etc/sysconfig/illumon.d/client_update_service. The contents are added to getdown.txt.

For example, if /usr/illumon/latest/etc/JAVA_VERSION contains the value 17, then the contents of the file /etc/sysconfig/illumon.d/client_update_service/getdown.java.17 is added to the generated getdown.txt.

Each of these version-specific getdown files includes the appropriate server_java_version setting, which should not usually be changed. The Deephaven Launcher reads this property and requires that Deephaven be started with a matching Java version, where matching means that the version from java -version starts with xx.

This functionality requires Launcher 8.14 or higher, and appropriate settings on the server.

The Launcher will try the version used to run the Launcher first. If that doesn’t match, it will present dialogs allowing the user to select a new JDK. One option is to continue with an "invalid" version, primarily to handle future unforeseen situations.

Changing the Java version is a complex operation that requires installation of the new JDK and re-installation of the application with correct options; this is not addressed here.

Default landing page

The default page (index.html) contains overview information about the Deephaven client and provides installer downloads. The file is located in /usr/illumon/latest/cus/iris and cannot be edited easily because each installation will overwrite it.

Error landing page

getdown.txt includes the ui.install_error entry which points to the error page. This page is loaded for certain download errors, and provides contact information for Deephaven Data Labs support.

Providing a different file for this error page is not supported. The HTML file is located at /usr/illumon/latest/cus/iris/error.html and can be edited, but it will be overwritten by the next Deephaven installation.

Classpath

The following lines set the classpath for client Java processes. Java processes search for classes and resources in these locations, in the order given. Most Deephaven files are in the resources and java_lib directories. Additional locations are provided to enable customization and overrides.

There are separate settings for classpaths on Windows, Linux, and OSX.

jvmarg = -classpath

jvmarg = [windows] "%APPDIR%\private_classes;%APPDIR%\private_jars\*;%APPDIR%\override;%APPDIR%\hotfixes\*;%APPDIR%\config;%APPDIR%\resources;%APPDIR%\java_lib\*;%APPDIR%\plugins\hotfixes\*;%APPDIR%\plugins\override;%APPDIR%\plugins;%APPDIR%\plugins\*;%APPDIR%\customer_jars\*"

jvmarg = [linux] %APPDIR%/private_classes:%APPDIR%/private_jars/*:%APPDIR%/override:%APPDIR%/hotfixes/*:%APPDIR%/config:%APPDIR%/resources:%APPDIR%/java_lib/*:%APPDIR%/plugins/hotfixes/*:%APPDIR%/plugins/override:%APPDIR%/plugins:%APPDIR%/plugins/*:%APPDIR%/customer_jars/*

jvmarg = [mac] %APPDIR%/private_classes:%APPDIR%/private_jars/*:%APPDIR%/override:%APPDIR%/hotfixes/*:%APPDIR%/config:%APPDIR%/resources:%APPDIR%/java_lib/*:%APPDIR%/plugins/hotfixes/*:%APPDIR%/plugins/override:%APPDIR%/plugins:%APPDIR%/plugins/*:%APPDIR%/customer_jars/*

Directory cleanup

The clean_target and clean_target_resource lines in getdown.txt values specify directories under the instance directory whose contents should be completely replaced when updating. This is required for parts of the classpath that use wildcards to find JARs whose names will change from version to version, and to handle resources that are removed. Any files in directories named by a clean_target or clean_target_resource line will be removed unless they are named on a code = or resource = line.

Deephaven Launchers with version <= 8.15 do not look at resource = when handling clean_target, and do not process clean_target_resource. Directories that might contain resource = resources should use clean_target_resource.

Sources include:

clean_target = java_lib

<numerous clean_target entries follow>

clean_target_resource = calendars
clean_target_resource = chartThemes

While it is possible to add additional values for clean_target and clean_target_resource to getdown.global, in practice, it is very rare to need to do so. Do NOT edit targets in getdown.txt.pre, as they will be lost upon upgrading.

Code and resources

Code and resource entries in getdown.txt identify specific files for which digest values should be calculated, and that the Launcher should pull down to a client. The base path for these files is the system's temporary directory, e.g., /tmp/cus7948278661189215940/. The reload function of the Client Update Service creates symbolic links to (or, in some cases, directly copies) resources in several server directories before regenerating getdown.txt and updating the digest. The default sources are:

• /usr/illumon/latest/java_lib/
• /etc/sysconfig/illumon.d/java_lib/
• /etc/sysconfig/illumon.d/override/
• /etc/sysconfig/illumon.d/hotfixes/
• /etc/sysconfig/illumon.d/integrations/
• /etc/sysconfig/illumon.d/resources/
• /etc/sysconfig/illumon.d/calendars/
• /etc/sysconfig/illumon.d/chartthemes/
• /etc/sysconfig/illumon.d/dh-config/

Certain items are excluded, such as configuration files not needed by client installations. It will also include all the properties files stored in etcd; if you update your properties in etcd, you will need to reload the Client Update Service to have those new files sent to client machines.

Additional files Deephaven clients need may be added to /etc/sysconfig/illumon.d/java_lib/ or /etc/sysconfig/illumon.d/resources/. These files will also be included in the classpath of server processes. Individual code entries can be added to getdown.global to make files available to clients.

Like many other text configuration files, getdown.global, getdown.txt, and getdown.txt.pre use the pound/hash symbol (#) to indicate comment lines.

Providing additional resources to clients

The Deephaven Launcher can be configured to provide custom resources to launcher and downloader clients. On the server these resources should be owned by the Deephaven administrative user, typically irisadmin.

Resources can be placed in two locations on the server.

• /etc/sysconfig/illumon.d/resources contains resources that are available to the processes running on the server and are provided to clients.
• /etc/sysconfig/illumon.d/client_update_service/resources contains resources that are only copied to clients. These resources are not available to the server processes.

To provide custom resources to clients, follow these steps.

1. If the resource is only for clients and should not be available to server processes, create the /etc/sysconfig/illumon.d/client_update_service/resources directory if it doesn't exist.

2. Place the resources in the appropriate directory.

3. Reload the CUS.

4. The new resources will be copied to <program files>/<instance>/resources the next time the launcher or download is run.

Launcher properties files

Properties files and JAR files are downloaded automatically from the Deephaven server by the Launcher, so no persistent changes can be made by editing these files on the client. To make changes persistently and for all clients, make the changes on the server.

To apply configuration changes to the properties of specific client installations, add property keys and values to one of the jvmargs.txt files on that client's machine. There are several copies of this file that have varying levels of applicability depending on the location. All locations are relative to the workspace root.

• <WorkspaceRoot>/jvmargs.txt - applies to all instances for this client.
• <WorkspaceRoot>/<instance_name>/jvmargs.txt - applies to all workspaces and consoles in the instance.
• <WorkspaceRoot>/<instance_name>/workspaces/<workspace_name>/jvmargs.txt - applies to this Deephaven workspace.
• <WorkspaceRoot>/<instance_name>/workspaces/console/jvmargs.txt - applies to consoles in the instance.

Settings from all applicable files will be combined. If there are settings that exist in more than one of the files, the last one evaluated will take precedence. They are evaluated in the order listed above. The settings in the jvmargs.txt files also override settings from properties files.

The format of jvmargs.txt is similar to other properties files in that blank lines are ignored and comments start with a pound/hash (#) symbol. Because this file is being used to pass extra arguments into the Java command line, most of its key=value entries will start with -D. For example:

-DCsvExport.useFileSelectionDialog=true

Client Update Service Logs

The CUS is hosted by the Web API Service and will log to the same files inside /var/log/deephaven/web_api_service. These logs can be used to diagnose issues or be sent to Deephaven support.

Installation Location Information

Three types of files are stored during Deephaven Launcher installation and operation:

• Deephaven Launcher program files - These are the files required to run the Deephaven Launcher. These files do not change, and they do not contain data, downloaded JARs, or workspace files. On Windows clients, these files are installed on a per-user basis or per-machine basis, depending on the installation option chosen.
• Program files (also known as instance files) - These files include the JARs and the configuration files downloaded and synchronized for each instance, as well as log files generated by the Deephaven Launcher and Console programs.
• Workspace files - These files are workspace settings, backups, and history files.

The Deephaven Launcher displays the locations of Workspaces, Program, and Log files at the bottom right, as shown here:

Deephaven Launcher program files

Whether or not the Deephaven Installer is used for the installation, the program will be started from a working directory containing the shell script or executable, and supporting JAR and resource files.

Program files

A Deephaven instance specifies the server and port to which Deephaven should connect for that session. Users can configure multiple instances in the Deephaven Launcher.

The <programfiles>/<instance>/getdown.txt file enables an instance to appear as a choice in the Launcher. For example, if programfiles/foo/getdown.txt exists, then "foo" will be listed as an instance.

By default, program files and log files are stored under the following locations:

• Windows: %LOCALAPPDATA%/illumon
• macOS and Linux: ~/iris/.programfiles

Workspace files

Multiple workspaces can be created for each Deephaven instance. In the Launcher, the Workspace drop-down menu will list all available Workspaces for the selected Instance.

By default, workspace files are stored under the following locations:

• Windows: ~/Documents/Iris
• macOS and Linux: ~/iris/workspaces

For example, instance "foo" and workspace "Default" will be in ~/iris/workspaces/foo/workspaces/Default.

Deephaven Launcher Properties files

When the Launcher starts, it reads properties from all the launcher properties files it can find. Property values will be updated to replace a leading ~ or ${user.home} with the user's home directory. Files will be loaded in the order shown below. Later property settings override earlier ones, and system properties always have precedence.

Deephaven Launcher and system-wide program properties file

The Launcher properties file (illumon.launcher.properties) is located in the Deephaven Launcher program folder under the lib directory.

Per-user properties file

The per-user properties file (.illumon.launcher.properties) is located in the user's home directory:

• Windows: %USERPROFILE%\.illumon.launcher.properties
• macOS and Linux: ~/.illumon.launcher.properties

Instance properties files

The .illumon.launcher.properties files located in each instance folder are only used for that instance.

Properties relevant to the Deephaven Launcher