Deploying Your SmartDesktop

A simple analogy is that a Finsemble SmartDesktop is a desktop-deployed web app. Finsemble displays web assets using a technology we call a "container". As such, deploying Finsemble consists of three aspects.

  • First, there are assets that are deployed to a hosting server.
  • Second, there is an executable that installs the container to end users' desktops. The executable can be distributed to users' desktops like any other software. Once installed, a desktop icon and Start menu entry for your SmartDesktop are created. When an end user clicks the desktop icon, your SmartDesktop is built from the assets on your server.
  • Lastly, there are methods for updating your SmartDesktop. In general, updates are handled in a similar manner to updating a website.

This tutorial will step through these three aspects of deployment.


Web server hosting

Your components and assets need to be hosted on a web server so they can be retrieved by your end users.

The hosting servers can be internal—inside your firewall and accessible only to people on your corporate network—or external—available to anyone with internet access. A Finsemble SmartDesktop can be made of components hosted on a mixture of internal and external servers. Ideally, all of the components would be hosted from the same server because this allows for the faster Shared Worker communication. For details, see the Router documentation.

To host your assets:

  1. Ensure that component URLs are correct for production. These URLs are (typically) found in config/application/component.json.
  2. Ensure that your manifest URLs are correct for production. There are several paths defined in config/application/manifest-local.json that will need to be updated: crucially, your configuration variables.
    • URL variables are an important tool for deployment because they allow you to control the environment: development, staging, or production. If components are built as part of Finsemble, use $applicationRoot as the URL base.
  3. Build using a build system.
  4. Copy the finsemble folder to your $moduleRoot location, as defined in your manifest.
  5. Copy the contents of the dist folder to your $applicationRoot locations, as defined in your manifest.
  6. Create the URL to your manifest file. This is done by using the URL used in $applicationRoot and adding configs/application/manifest-production.json after it. Example: http://webserver/path/to/finsemble/configs/application/manifest-production.json. The URL for your manifest file is required for your installer (detailed below).

Creating an installer

Just as with applications like Skype or Spotify (both of whom use Electron as their container, just like Finsemble), you can use an installer to distribute your Finsemble application to your users' machines. The Finsemble seed project comes with a utility function for generating an installer.

To create an installer:

  1. Ensure that configs/other/server-environment-startup.json has a property called production and that the values match your deployed application. The installer and node server depend on this file to accurately serve your files. Example:
  "production": {
      "serverPort": 3375,
      "serverConfig": "http://localhost:3375/configs/application/manifest-local.json",
      "clientRoute": "http://localhost:3375/",
      "container": "electron",
      "electronDebug": true,
      "breakpointOnStart": false,
      "updateUrl": "http://localhost:3375/pkg"
  }
  1. Open configs/other/installer.json and modify the properties. Each property is defined in the Config Reference. The actual name of your SmartDesktop's runtime is set during this process.
  2. Run npm run makeInstaller:prod using a command prompt. Note: This process will take several minutes.

By default, the output will be placed into the finsemble-seed/pkg folder. When the installer executable runs, it will install your SmartDesktop, create a launch icon, and start the application.

Signing an installer

Code signing is built into the installer creation. Add the following properties to the installer.json file to create a signed installer:

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

Set password as null, or omit entirely, to provide password through an environment variable - INSTALLER_CERTIFICATE_PASSPHRASE.

You can set the environment variable at runtime using the command: INSTALLER_CERTIFICATE_PASSPHRASE=****** npm run makeInstaller:env

The example signWithParams above will pass the provided params to the Windows SignTool. This will fetch a timestamp from the included server. For more information see Config Reference.

Specifying Manifests at Run Time

By default, Finsemble will use the manifest that is bundled into the exe. However, you can specify manifests at run time. To enable this feature, your initial manifest must contain configuration for what manifests are allowed under the finsemble-electron-adapter config.

If you only want to allow specific manifests, you can make an entry under the manifests property:

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

These can be used either from the command line or using the fsbl protocol: Project.exe --manifest dev or fsbl://manifest/dev

If you want to allow any URL from specific hostnames, you can make an allowedManifestDomains entry:

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

This will allow any urls where the hostname matches one of the entries. Every subdomain needs an entry. Wildcards are not allowed.

This can be used either from the command line or using the fsbl protocol: 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

If you are using the protocol, ensure that the URL is encoded.

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

If there are problems with a manifest specified using one of the above means, Finsemble will load with the default manifest bundled into the exe.

Updates

Web deployment of your assets means that updating Finsemble is easy: simply replace the assets on your server with your updated assets. Updating functionality is a simple matter of adding new assets to your Finsemble "site" or just deploying those assets separately. When you need to update Finsemble, replace the files at the $moduleRoot URL in your manifest to point to the latest version of the Finsemble folder.

Updating your container

Your container can be configured to auto-update itself. Auto-update is an easy way to keep your users’ SmartDesktops up to date with the latest security patches. When configured for auto-update, Finsemble queries your server to check for new versions every time that it starts. When new versions are available on the server, they are automatically downloaded and installed.

Your release team has complete control over when to make new versions available. Simply upload a new release to your server (http) and it will become available as an auto-update for all your users. Users are prompted whenever new versions are installed and asked whether they wish to restart with the new version or continue on with the prior version.

Configuring your SmartDesktop to auto-update

  1. Set updateURL in configs/other/server-environment-startup.json to point to the URL where updates will be hosted (under the production config!). Note: In the seed project, installers are built to the pkg folder. Updates can be hosted in the seed project by setting the updateUrl to http://localhost:3375/pkg.
  2. Set version in configs/other/installer.json to an updated version number.
  3. Ensure that the pkg directory in your application root contains both the .nupkg and RELEASES files that were generated last time you created a package.
  4. Generate a new "package" by running npm run makeInstaller:prod in the root of your application's directory. The new versions of .nupkg and RELEASES files will be added to the pkg folder.
  5. Upload the pkg folder to your server, which you specified in step 1.

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 it is needed for performing updates. The delta nupkg file contains the delta between the binary files. This is smaller and quicker to deploy than a full installation.

The RELEASES file in the pkg folder is what contains information about all previous updates. When updating: (1) the new package is downloaded and installed on the end user’s computer, (2) shortcuts are updated, and (3) older versions of the container are saved in a folder with the version number.


Video of building a self-updating installer

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

Finsemble Building an Auto-Updating Installer Video
check   Finsemble is a collection of smaller web pages and native apps served from an HTTP server—just like a website. Deployment is nothing more than copying your dist and finsemble directories to your production server and using an installer to get Finsemble onto your users' machines.
 

Further reading

For a more thorough discussion of what Finsemble physically is and how it's structured, read the Architectural Overview.

If you choose to incorporate native components (.EXE, Java, Flash, etc.) into a Finsemble application, you must use the Windows executable assimilationMain.exe. Read about how to bundle applications with your SmartDesktop here.

For more on the build process, read the Build Process tutorial.