Skip to main content

Self-host the Browser component

By default, the Browser component code is served to desktops from a Here™ server, which ensures that users always run the most current stable version. Starting in version 20.1, you can host the Browser component code within your own secure environment, eliminating dependencies on external CDNs and giving you control over component versions.

The Browser component code for self-hosting is provided in a zipped ASAR (Atom Shell Archive) file. This file is digitally signed by OpenFin, to ensure that its integrity can be verified.

Note: The self-hosted Browser component runs without other Here Core UI components. It is not supported to work with components hosted by Here™, and other Here Core UI components do not currently support self-hosting.

Prerequisites​

  • Workspace SDK version 20.1 or greater

  • A web server for hosting the Browser file

How it works​

  1. Your organization downloads the zipped ASAR file for a specific release of Here Core UI Components.

  2. You place the file on a server accessible to your users.

  3. You configure the application manifest for your Here Core UI platform to reference the ASAR file, including the server location and an alias value.

  4. You add a declaration for the secured API serveAsset to the manifest file.

  5. Because this solution uses a secured API (serveAsset), the permission to use the API must be granted by the desktop owner, by the end-user, or by Here™. If your organization controls the systems where the software runs, then it can allow the secured API through desktop-owner-settings. Otherwise, end-users might be prompted to approve the use of this method, which is often undesirable. Alternatively, if your organization does not control the desktop systems, you can set up your Here Core UI platform with a trusted application configuration.

  6. In your code to initialize the Here Core UI platform, you specify the same alias value as in the application manifest.

  7. When the user launches the Here Core UI platform, the platform accesses the ASAR file, verifies the file signature, and downloads the assets needed to launch the Browser component.

How to do it​

Set up the ASAR file​

The zipped ASAR file is named workspace-platform.zip, and is located in the root directory of the web page for the Workspace Platform npm package. You can download it from there.

Place the zipped ASAR file on a web server that you control, so that the URL of the file is accessible to users in your organization.

Configure the app manifest​

Add the Browser ASAR file as an app asset in the manifest file for the Here Core UI platform. For details about the appAssets object, refer to Manifest settings.

Add serveAsset to the list of secured APIs used by the application. Refer to API security for details about secured APIs.

{ 
…
    "appAssets": [{
        "src": "https://INTERNAL_SERVER.com/workspace_platform.zip",
        "alias": "ALIAS",
        "version": "VERSION_OF_THE_WORKSPACE_PLATFORM_PACKAGE",
        "target": "workspace.asar"
    }], 
    "permissions": {
      "System": {
        "serveAsset": true
      },
…
}

  • src: The host name in the src value is used for cache migration, and must be unique across all appAssets definitions used by a Runtime on the desktop system.

  • alias: The value defaults to "workspace"; it is recommended to use a custom, unique alias.

  • version: As a best practice, match the Workspace Platform package version; this is not strictly required, but reduces confusion. The value must be updated when the version of the workspace-platform package is updated.

  • target: Required to enable retrieving the correct file from inside the zipped file. The value must be "workspace.asar".

Obtain permission to use the secured API​

By default, if nothing else is done, the end-user will be prompted to grant permission to use the secured API, the serveAsset method. Often, this is an undesirable user experience. To avoid prompting the end-user, you can do one of the following:

  • If your organization controls the systems where the Here Core UI platform runs, you can grant permission in desktop owner settings. Refer to API security for desktop owners for details.

  • If your organization does not control the systems, you can request Here™ to authorize your Here Core UI platform as a trusted application configuration. In this case, Here™ provides you with a signed, encrypted configuration to add to your application manifest.

Initialize the Here Core UI platform with the hosted file​

When you initialize the Here Core UI platform, include the alias value that is defined in the manifest file.

import * as WorkspacePlatform from '@openfin/workspace-platform';

await WorkspacePlatform.init(
  {
    browser: { // Define Browser configuration here
    },
    workspaceAsar: {
      alias: "ALIAS"
    }, //…
  }
)

Limitations​

  • An instance of the ASAR file can be used for only one Here Core UI platform provider. If your environment includes multiple Here Core UI platform providers, they must each have their own copy of the ASAR file.

Table of Contents