Deploying your smart desktop

A simple analogy is that a Finsemble smart desktop is a desktop-deployed web app. Finsemble displays web assets using a technology we call a "container". Deploying your smart desktop involves three steps:

Host the Finsemble platform (Finsemble's web assets) on a web server. Your smart desktop loads these assets when it launches.
Host your apps (the individual windows that make up your smart desktop). Apps may be web or native. Web apps must be hosted by a web server. Native apps must be installed independently on user desktops or hosted as an "appAsset" (a zip file containing the native executable that your smart desktop downloads and runs at launch time).
Create and deliver an installer to your end users' computers. Your installer installs your smart desktop's "runtime" (an executable). It then creates a desktop icon and Start menu entry to launch your smart desktop.

This tutorial provides these steps for (1) initial deployment and (2) upgrades.

1. Hosting the Finsemble platform

The assets that make up the Finsemble platform are in the public folder of your seed project. To deploy your smart desktop, you must host this folder on your web server (either secure or insecure, on your intranet or on the Internet).

Finsemble's manifest file (public/configs/application/manifest-local.json) is the entry point for your smart desktop. When your smart desktop launches, it first loads the manifest and then uses the contents of the manifest to find the locations of other assets.

See Using Manifests To Manage Multiple Deployment Environments to learn how to create multiple manifests for different deployment scenarios (such as development, production, etc).

To host the Finsemble platform:

Run npm build:prod
Copy the public directory to your web server.
Make a note of the url for your manifest file.

2. Hosting your apps

Your apps can be hosted anywhere. Each app's location is set in the manifest.window.url entry in appd.json. Each of these entries can be either an absolute path, a path relative to the manifest location, or a path relative to a manifest macro. See Using Manifest Macros.

Finsemble's built-in UI components and any applications you add to Finsemble's seed project with Finsemble's CLI will be in the src/components directory and are compiled into the public/build/components directory. Your appd.json entries will then typically look like: $applicationRoot/components/yourappfolder/yourapp.html. But&emdash;you can host your apps anywhere, and use any build process, so long as appd.json entries point to the correct locations.

3. Creating your smart desktop installer

Edit `server-environment-startup.json`

Update configs/other/server-environment-startup.json so that the URLs, ports, and other values match your web server.

This file provides samples for development and production environments. You can add or rename your environments. See Creating Multiple Installers For Different Environments.

Example:

{
  "production": {
      "serverConfig": "https://site.yourfirm.com/configs/application/manifest-local.json"
  }
}

Most of the entries in server-environment-startup.json relate to development and debugging. You can ignore or remove those for deployment.

Edit `installer.json`

Edit configs/other/installer.json with the settings you want for your smart desktop executable:

name - the name of your smart desktop
version - the version number (this appears in the executable's properties on Windows and controls auto-updates to the runtime)
icon - path to the smart desktop icon for Windows (must be an .ico file)
macIcon - path to the smart desktop icon for Mac (must be an .icns file)
loadingGif - image to display when your smart desktop is installing on Windows (must be a .gif file)
background - image to display when your smart desktop is installing on Mac (this must be a .png file)
author - the author(s) or publisher of the smart desktop (this appears in the executable's properties on Windows)
description - a description of the smart desktop (this appears in the executable's properties on Windows)

osxSign - a JSON object required for codesign execution (required for you app to be notarized on OSX)

osxSign: {
  identity: "Developer ID Application: Cosaic (**********)" // Name of certificate to use when signing. Platform darwin will look for Developer ID Application: * (*) by default.
  entitlementsFile: "./public/configs/other/entitlements.plist" // Path to entitlements file for signing the app.
}

osxNotarize - a JSON object required for app notarization
```
osxNotarize: {
  appleId: "developer@cosaic.io" // The username of your Apple developer account
  appleIdPassword: "xxxx-xxxx-xxxx-xxxx" // The app-specific password (not your Apple ID password).
}
```
Note: Do not include osxSign AND osxNotarize if you do not wish to notarize your MacOS app. These properties will be ignored if you are building a windows installter.

Use a “Developer ID” application certificate for your code-signing signature. You can read more about preparing your software for notarization here.

Caution: Be sure that the paths to your icons and images are the correct image format. An incorrect format can cause your smart desktop to crash during launch.

See Signing an installer for setting the certificate entries.

Build your installer

Run yarn makeInstaller:prod (or npm run makeInstaller:prod) to build the installer for the production environment.

Installer generation can take several minutes.

The installer will be placed in the outputDirectory that is set in installer.json. (The default location is ./pkg).

Your smart desktop is ready! You can now deliver it to your users.

Finsemble doesn't provide a standard method for distributing executables. We recommend consulting with your IT administrator. Many firms prefer to install executables using group policy.

By default, installers are built for the same platform as they themselves were built on. And so, running makeInstaller on Windows creates a Windows installer. It is possible to build a Windows installer on Mac or Linux using Mono and Wine by setting the BUILD_WIN32 environment variable to true.

When you run this installer, it will set 2 registry keys, no elevated privileges needed:

HKEY_CURRENT_USER\SOFTWARE\Classes\fsbl\shell\open\command is created on the first run of the exe you just created.
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall{INSTALL_NAME}, where INSTALL_NAME is the value of the name field in your install.json config file.

Updating your deployed smart desktop

1. Update your apps

You can update your apps at any time by deploying updated files to your web servers. New versions of your apps become available to end users when they restart their smart desktop

2. Update the Finsemble platform

Replace the assets on your server with your updated assets (e.g. the public directory in your seed project).

It is necessary to update the Finsemble platform and runtime executable only when:

You've upgraded to a new version of the Finsemble library (in your package.json); or
You've changed installer parameters; or
You've customized any of Finsemble's UI components, such as Toolbar or WindowTitle Bar.

3. Update the smart desktop runtime

You can update the smart desktop either by pushing a new version to your users' desktops (e.g. via group policy) or by configuring your smart desktop for auto-update.

The choice of pushing releases or auto-updating depends solely on your firm's deployment preferences.

When configured to auto-update, your smart desktop checks your web server for new versions when it launches. New versions on the web server are automatically downloaded and installed. Simply upload a new release to your web server whenever you are ready for your end users to receive updates.

Auto-update downloads occur silently unless you set finsemble.waitForUpdate to true in your manifest. With waitForUpdate, your smart desktop will pause during launch and restart when the new version is downloaded.

Configuring auto-update

Before generating your installer, set updateUrl in server-environment-startup.json to point to the URL where updates will be hosted (be sure to set this entry in your production environment!).

Save the .nupkg and RELEASES files from your output directory. These can be used to generate differential update files to speed up future updates.

Example server-environment-startup.json:

 "production" : {
    ...
    "updateUrl" : "http://production.myfirm.com/updates"
    ...
  }

Then, to release new versions for auto-update:

Set version in installer.json to an updated version number.
(Optional) To create a differential update, ensure that your outputDirectory already exists and contains both the .nupkg and RELEASES files that were generated last time you created an installer.
Run npm run makeInstaller:prod. New versions of .nupkg and RELEASES files will be produced. Once again, save .nupkg and RELEASES for future upgrades.
Upload the contents of your outputDirectory to the location you specified in updateUrl.

The nupkg file has several purposes. When generating an update, two nupkg files are generated: full and delta. The full nupkg file isn't used for installation, but can be used for updates. The delta nupkg file contains the delta between the binary files. This is smaller and quicker to deploy than a full installation, but is only produced if you retained the full nupkg file from previous versions.

The RELEASES file in the pkg folder contains information about all previous updates. When updating:

the new package is downloaded and installed on the end user’s computer
shortcuts are updated
older versions of the container are saved in a folder with the version number.

Video: Building an auto-updating installer

Our Director of Solutions Engineering, Andy Gardner, walks you through the steps needed to create a self-updating installer in this video.

Video: Building an Auto-Updating Installer

Advanced topics

Signing an installer

You can code sign your installer so that your smart desktop can be installed in tightly controlled environments. To sign your installer, add these properties to the installer.json file before running yarn makeInstaller.

 ...
  "certificateFile": "C:/path/to/cert/file.pfx",
  "certificatePassword": "*********",
  "signWithParams": "/tr http://timestamp.digicert.com"
}

You can also set the certificate password through the environment variable INSTALLER_CERTIFICATE_PASSPHRASE (when certificatePassword is removed or set to null in installer.json).

To set the environment variable at runtime, use this command (syntax may vary depending on your shell): INSTALLER_CERTIFICATE_PASSPHRASE=******; yarn run makeInstaller:env

Code signing on Windows is through Authenticode.

Microsoft Windows installers require a timestamp server. Installer generation will fail if the "signWithParams": "/tr http://timestamp.digicert.com" line is missing. The installer uses Windows SignTool. You can pass along any SignTool command line argument by adding it to signWithParams.

Using manifest macros to optimize complex deployments

Finsemble supports these macros, each of which tell Finsemble's runtime where to load portions of the platform. These macros are set automatically by the runtime but you can also explicitly set them if you want to change their location.

$documentRoot - points to the document root of the Finsemble platform—the assets that are deployed to your web server (typically the public folder in the seed project). The default is ../../ (which is the relative path from manifest-local.json to public).
$applicationRoot - the location of apps, adapters and preloads. The default is $documentRoot/build (typically everything that is built from your seed project's src directory).
$moduleRoot - the location of the deployed core Finsemble platform files. The default is $documentRoot/finsemble. (These files are generated automatically when you run yarn dev in the seed, copied from the finsemble-core npm package.)
$servicesRoot - the location of the core Finsemble platform services. The default is $moduleRoot/services.
$configRoot - specifies the location of importable config files. The default is $documentRoot/configs.

Macros are set in the finsemble section of the manifest. They can be set with either absolute paths, paths relative to the location of the manifest file, or relative to other macros.

Example: Set documentRoot to an absolute path.

manifest-local.json

"finsemble" : {
  "documentRoot": "http://production.myfirm.com/an/arbitrary/location"
}

Example: Set applicationRoot to a relative path. Relative paths are relative to the location of the manifest file.

http://myserver.com/arbitrary/location/manifest-local.json

"finsemble" : {
  "applicationRoot": "../../build"
}

$applicationRoot will now be equivalent to "http://myserver.com/build".

Creating your own manifest macros

You can create your own manifest macros and use them throughout the config. Custom macros are set by adding entries to the finsemble.custom section of the manifest.

Using manifests to manage multiple deployment environments

You can create multiple manifest files to deploy multiple versions of your smart desktop. Each manifest can use manifest macros to point to different hosted assets.

Example: Multiple manifests within your hosted assets to handle development, staging, and production environments.

Directory structure of seed project

seed/
  configs/
    application/
      manifest-development.json
      manifest-production.json
      manifest-staging.json

Example: Setting the documentRoot manifest macro to point to hosted assets on a staging server.

manifest-staging.json

  "finsemble" : {
    "documentRoot" : "http://staging.mycompany.com/smartdesktop"
  }

In each manifest, you can set startup_app.uuid to a unique value per environment. The storage adapter for each environment may then use the uuid to generate unique storage keys, resulting in separate data sets (workspaces, favorites, etc) per environment.

Launching your smart desktop with alternate manifests

There are two ways to point your smart desktop at a different manifest:

Build a new installer with the serverConfig entry pointing to the manifest URL you want

See Edit server-environment-startup.json
Launch your smart desktop with a command line argument pointing to the manifest URL you want:

Finsemble uses a default manifest that is hosted at the URL bundled into the runtime (the embedded manifest URL). For security reasons, the default manifest will always be loaded and allows you to set configuration that will permit loading of specified alternative manifests or arbitrary manifests hosted on specified domains. This ensures that you control what manifests your installed and branded copy of Finsemble can be used to load and prevents spoofing via a desktop shortcut or protocol handler link.

Once configured in the default manifest, your smart desktop executable can be launched with an alternative manifest either via specific command line parameters (--manifest-name or --manifest-url) or by launching your smart desktop through a protocol handler (fsbl://manifest or fsbl://manifest-url).

The configuration necessary to enable runtime manifests is set in the finsemble-electron-adapter section of the default manifest. To allow only specific manifests to be used, create entries in finsemble-electron-adapter.manifests that map names to manifest locations:

Example:

  "finsemble-electron-adapter": {
        "manifests": {
            "dev": "http://localhost:3375/configs/application/manifest-local-dev.json",
            "qa": "http://localhost:3375/configs/application/manifest-local-qa.json"
        }
    }

You can now use these names to launch your smart desktop with one of the specified manifests: Project.exe --manifest-name dev or fsbl://manifest/dev (You'll need to create a new installer to test this).

As an alternative to mapped entries, you can pass arbitrary manifest urls at run time: Project.exe --manifest-url http://cosaic.io/configs/application/manifest-local-dev.json or fsbl://manifest-url/http%3A%2F%2Ffinsemble.com%3A3375%2Fconfigs%2Fapplication%2Fmanifest-local-dev.json

Finsemble validates the domains for any runtime url against the finsemble-electron-adapter.allowedManifestDomains entry:

"finsemble-electron-adapter": {
    "allowedManifestDomains": [
        "finsemble.com",
        "cosaic.io"
    ]
},

Your smart desktop exits with a dialog for the user if the requested url is invalid.

Hostnames must be an exact match. The only available wildcard is "*", which allows any run time url.

Ensure that your url is urlencoded when using a protocol handler (see above example.)

You can use both manifests and allowedManifestDomains together. URLs specified in the manifests property don’t need to be from one of the domains specified in allowedManifestDomains.

Creating multiple installers for different environments

By default, installer.json contains a single configuration. To specify unique installer configs for each of your environments, modify installer.json to have multiple entries. Each entry key must match an environment name from server-environment-startup.json.

Example:

server-environment-startup.json

{
  "development": {
    "icon": "./public/assets/img/installer_dev_icon.ico",
    "version": "5.0.0",
    ...
  },
  "production": {
    "icon": "./public/assets/img/installer_icon.ico",
    "version": "5.1.0",
    ...
    }
}

Use npx gulp to run makeInstaller with the optional command line argument --environment:<environment> (or set the environment variable NODE_ENV to the environment you want).

Example: Make an installer with config from a "emea" environment.

npx gulp makeInstaller --environment:emea

A strategy for reliable upgrades and rollbacks

For every upgrade, we recommend that you create a new Finsemble platform folder and point each smart desktop version at a new manifest within that folder. This ensures that previous versions of your smart desktop continue to run with compatible assets. Users stuck on previous versions will not experience problems. Your firm can also use this strategy for rollbacks or to perform staged upgrades.

Example: Dedicated folders and manifests for two versions of the same smart desktop.

Web server document root for http://production.yourfirm.com/

doument_root/
  updates/
    .nupkg
    RELEASES
    ...
  5.0/
    configs/
      application/
        manifest.json
        ...
    build/
    assets/
  5.1/
    configs/
      application/
        manifest.json
        ...
    build/
    assets/

Dealing with unreliable network connections

Finsemble supports configurable retries and timeouts through command line flags.

YourSmartDesktop.exe --manifest-timeout=30000 - specify a custom timeout (in milliseconds) for fetching the manifest. Defaults to 10 seconds.
YourSmartDesktop.exe --manifest-retries=5 - specify that Finsemble should retry X attempts to fetch the manifest in case of failure or timeout. Defaults to 5.

Finsemble logs all network errors. This can be useful when dealing with startup problems or misbehaving components. Those errors show up in the log as "[error]: webRequest.onErrorOccurred" with a JSON string describing the error.

By default, all debugging and errors are logged to the FEA log, which can be found in your $AppDir/<projectname>/logs/ directory (e.g. /users/william/AppData/roaming/<Your App Name or "Electron">/logs/FEA-2020-11-16.log). You can also optionally display logs in the console by setting the command line argument --enable-console. This can be useful when debugging while developing.

You can also configure command line arguments in your project's server-environment-startup.json file.

"development": {
  "args": ["--manifest-timeout=15000", "--manifest-retries=5", "--enable-console", "--log-network-errors"],
  ...
}

Silent installs

To execute a silent install of your smart desktop, use the command line to run the installer with the --silent flag.

$ installer.exe --silent

Deploying your smart desktop

1. Hosting the Finsemble platform

2. Hosting your apps

3. Creating your smart desktop installer

Edit server-environment-startup.json

Edit installer.json

Build your installer

Updating your deployed smart desktop

1. Update your apps

2. Update the Finsemble platform

3. Update the smart desktop runtime

Configuring auto-update

Video: Building an auto-updating installer

Advanced topics

Signing an installer

Using manifest macros to optimize complex deployments

Creating your own manifest macros

Using manifests to manage multiple deployment environments

Launching your smart desktop with alternate manifests

Creating multiple installers for different environments

A strategy for reliable upgrades and rollbacks

Dealing with unreliable network connections

Silent installs

See also

Edit `server-environment-startup.json`

Edit `installer.json`