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". 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 smart desktop are created. When an end user clicks the desktop icon, your smart desktop is built from the assets on your server.
  • Lastly, there are methods for updating your smart desktop. 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 smart desktop 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/openfin/manifest-production.json after it. Example: http://webserver/path/to/finsemble/configs/openfin/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 smart desktop'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 smart desktop, create a launch icon, and start the application.


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 the application config to point to the latest version of the Finsemble folder.

Updating your container

Your container can be configured to auto-update itself. Your release team pushes new releases up to a specified server location. Every time your smart desktop runs, it will query that server location and download the new container. The user is then prompted whether they wish to restart with the new version or continue on with the prior version.

To auto-update your container:

  1. Make sure an updateURL is set in configs/other/server-environment-startup.json under the production config. The value should be the URL where the installer is hosted.
  2. Change the version number in configs/other/installer.json to be the updated version number.
  3. Run npm run makeInstaller:prod under the root of your application's directory to generate the new version of your container. The installer will configure your container according to your configuration in installer.json. This includes the name and version of the smart desktop, its launch icon, and location of the application directory. The output directory (in this case the pkg folder) will be located under the root and includes the application executable, RELEASES file, and .nupkg file. Finsemble will check the files in this directory to determine if an update is available.
  4. Move the output directory to the updateUrl location set in your server-environment-startup.json config file.
  5. Finsemble will look for and install any updates in the background each time your smart desktop is executed. It checks the RELEASES file at the distribution location for any updates, downloads the update packages, updates app shortcuts, and cleans up older versions. Updating your deployed container is as easy as updating the application directory folder on your server. From the end user's perspective, every time the smart desktop launches, it will check for updates, and if there is one, it will download the updated version in the background and apply the updated version the next time the user launches the app. Finsemble leverages Squirrel Updater for Windows. This allows complete management of installation and updates in the most straightforward way possible.

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 smart desktop here.

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