Skip to main content

Self-host the Browser and Dock3 components

By default, the HERE Core UI Components code is served to desktops from a HERE server, which ensures that users always run the most current stable version. Starting in HERE Core UI version 20.1, you can host the Browser component code within your own environment, eliminating dependencies on external CDNs and giving you control over component versions. Starting in HERE Core UI version 23, the Dock3 component code is included alongside the Browser code for self-hosting.

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

note

The self-hosted components run without other HERE Core UI components. They are not supported to work with components hosted by HERE, and HERE Core UI components other than Browser and Dock3 do not currently support self-hosting.

Prerequisites​

  • For Browser only: Workspace SDK version 20.1 or later

  • For Browser and Dock3: Workspace SDK version 23 or later

  • For Windows deployments: A web server for hosting the component ASAR file

How it works​

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

  2. For Windows deployments, you place the ASAR file on a server accessible to your users. For macOS deployments, the ASAR file must be run from a local file path, so you must place it on each macOS device that will run HERE Core UI in self-hosted mode.

  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 APIs serveAsset and (on Windows) downloadAsset to the manifest file.

  5. Because this solution uses secured APIs, the permission to use the APIs 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.

For deploying to Windows systems, 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. For deploying to macOS systems, transfer the unzipped ASAR file (workspace.asar) to a local file path on each system.

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 and (on Windows) downloadAsset to the list of secured APIs used by the application. Refer to API security for details about secured APIs.

MS Windows platform manifest
{ 
// Root-level properties

    "platform": {
        "permissions": {
            "System": {
                "serveAsset": true,
                "downloadAsset": true
            }
        }
    },
    "appAssets": [{
        "src": "https://INTERNAL_SERVER.com/workspace_platform.zip",
        "alias": "ALIAS",
        "version": "VERSION_OF_THE_WORKSPACE_PLATFORM_PACKAGE",
        "target": "workspace.asar"
    }], 
    
// More properties
}
macOS platform manifest
{ 
// Root-level properties

    "platform": {
        "permissions": {
            "System": {
                "serveAsset": true
            }
        }
    },
    "appAssets": [{
        "path": "PATH_TO_FILE/workspace.asar"
    }], 
    
// More properties
}

  • 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".

  • path: (macOS only) Path on the local filesystem to the unzipped ASAR file.

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 APIs: the serveAsset() method, as well as downloadAsset() on Windows. 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