diff --git a/how-to/workspace-platform-starter/CHANGELOG.md b/how-to/workspace-platform-starter/CHANGELOG.md index c395bca38..2521acb8b 100644 --- a/how-to/workspace-platform-starter/CHANGELOG.md +++ b/how-to/workspace-platform-starter/CHANGELOG.md @@ -3,7 +3,7 @@ ## v20.1.0 - Removed the old platformProvider.intentPicker setting. The setting has been exposed through platformProvider.interop.intentResolver for a number of releases and is now the only way of setting the intent resolver. -- Added support for self hosting the Workspace Browser UI (html, js, css) and related settings through the new workspaceAsar setting introduced in 20.1. +- Added support for self hosting the Workspace Browser UI (html, js, css) and related settings through the new workspaceAsar setting introduced in 20.1 and added documentation around [self hosting workspace components](./docs/how-to-self-host-workspace.md) ## v20.0.0 diff --git a/how-to/workspace-platform-starter/README.md b/how-to/workspace-platform-starter/README.md index 03614a5df..0bb87d1c1 100644 --- a/how-to/workspace-platform-starter/README.md +++ b/how-to/workspace-platform-starter/README.md @@ -78,6 +78,7 @@ The information below provides information related to configuring and using the | [Secure Your Platform](./docs/how-to-secure-your-platform.md) | How would you secure your platform? What are some of the things you should consider when building your platform? | | [How To Add A Service](./docs/how-to-add-a-service.md) | How would you extend your platform to so that a service is started up when the application has finished it's bootstrapping process and started? | | [Deploy Your Platform Across Environments](./docs/how-to-deploy-your-platform.md) | How can you deploy your platform across environments? | +| [Self Host Workspace Components](./docs/how-to-self-host-workspace.md) | How can you self host workspace components such as the notification center or the Workspace Browser UI so that it isn't served from ? | | [Testing Your Platform Code](./docs/how-to-test-your-platform-code.md) | How would you test the code for your platform? | | [Testing Your Platform UI](./docs/how-to-test-your-platform-ui.md) | How would you test the UI for your platform? | diff --git a/how-to/workspace-platform-starter/docs/how-to-deploy-your-platform.md b/how-to/workspace-platform-starter/docs/how-to-deploy-your-platform.md index 469c8a6d0..30b41a4a4 100644 --- a/how-to/workspace-platform-starter/docs/how-to-deploy-your-platform.md +++ b/how-to/workspace-platform-starter/docs/how-to-deploy-your-platform.md @@ -134,4 +134,8 @@ Start the OpenFin app: start fin://localhost:8181/manifest.fin.json ``` +## Self Hosted Workspace Components + +If you are self hosting workspace components remember to include them in your deployments across environments. Please see [How To Self Host Workspace Components](./how-to-self-host-workspace.md) for more information. + [<- Back to Table Of Contents](../README.md) diff --git a/how-to/workspace-platform-starter/docs/how-to-self-host-workspace.md b/how-to/workspace-platform-starter/docs/how-to-self-host-workspace.md new file mode 100644 index 000000000..ce49b7560 --- /dev/null +++ b/how-to/workspace-platform-starter/docs/how-to-self-host-workspace.md @@ -0,0 +1,128 @@ +> **_:information_source: OpenFin Workspace:_** [OpenFin Workspace](https://www.openfin.co/workspace/) is a commercial product and this repo is for evaluation purposes (See [LICENSE.MD](../LICENSE.MD)). Use of the OpenFin Container and OpenFin Workspace components is only granted pursuant to a license from OpenFin (see [manifest](../public/manifest.fin.json)). Please [**contact us**](https://www.openfin.co/workspace/poc/) if you would like to request a developer evaluation key or to discuss a production license. + +[<- Back to Table Of Contents](../README.md) + +# How to self host Workspace Components? + +Self-hosting means serving the HTML, CSS, JavaScript and related files for a particular Component/UI from your own servers instead of of the Here domain: workspace.openfin.co. + +The two pieces that can be self hosted are: + +- Notification Center +- Workspace Platform - (the Browser UI and related files) + +This document covers how to enable self hosting when using the workspace platform starter (this can be used as a guide for your own implementation of a Workspace Platform and can complement the official documentation on our developer site). + +In all cases please ensure you are licensed to use self-hosting in production. + +## Self Hosted Notification Center + +Fetch the notification center files from our cdn and create your own notification manifest and host them on your own server as detailed here . + +Update your Workspace Platform Starter settings. Update the notificationProvider setting to add notificationsCustomManifest. This will specify your notification center uuid and the url for that manifest: + +```json +{ + "notificationProvider": { + ... + "notificationsCustomManifest": { + "manifestUrl": "", + "manifestUuid": "" + } + }, +} +``` + +## Self Hosted Workspace Platform Browser & Related Files + +This option is currently only available on Windows. + +From version 20.1 of the @openfin/workspace-platform npm package it will include a zip file called **workspace_platform.zip**. This file should not be unzipped or modified. It includes a workspace.asar file which is a zipped representation of the Browser UI and related files. This workspace_platform.zip file will be fetched from your server and extracted locally (through an app asset). When you launch a Workspace Browser Window you will be able to confirm that the file is sourced from the workspace.asar if the url for the UI comes from openfin:// as a url. + +The [public/manifest.fin.json](../public/manifest.fin.json) file has been updated with three main changes: + +### A new permission has been added - serveAsset + +The permissions requested by [public/manifest.fin.json](../public/manifest.fin.json) now includes serveAsset + +```json +{ + ... + "platform": { + ... + "permissions": { + "System": { + "serveAsset": true, + } + } + } +} +``` + +This is required in order to serve the Browser UI files from the workspace.asar file. + +### An app asset entry has been added + +The [public/manifest.fin.json](../public/manifest.fin.json) now includes an appAsset. + +To ensure the Browser UI files are ready for when your platform has finished bootstrapping it has been added as an app asset to the manifest. The RVM will see this entry and download and extract the app asset if it is not available even before launching your application. It will then be cached on disk and will only change if the version number is changed. + +```json +{ + ... + "appAssets": [ + { + "src": "http://localhost:8080/common/assets/workspace_platform.zip", + "alias": "self-hosted-workspace-platform", + "version": "20.1.0", + "target": "workspace.asar" + } + ] +} +``` + +The **src** should be the url where you have copied the **workspace_platform.zip** file. This may be an application server or your CDN. We have included it in public/common/assets to not require a build step and to simplify PoCs. + +The **alias** is important as it will be used when initializing your workspacePlatform. + +The **version** number should reflect the version number of the @openfin/workspace-platform npm package. + +The **target** has to be **workspace.asar** as that is the file contained within the workspace_platform.zip file. + +### A new setting in the platformProvider section of your Workspace Platform Starter configuration has been added + +We have extended the Workspace Platform Starter PlatformProvider Settings type so that you can specify a workspaceAsar and whether or not it should be enabled (to let you easily test self-hosting by setting a boolean flag). + +The alias must match the alias of the appAsset you have specified. + +```json +{ + ... + "customSettings": { + ... + "platformProvider": { + ... + "workspaceAsar": { + "enabled": false, + "alias": "self-hosted-workspace-platform" + } + } + } +} +``` + +**Set enabled to true if you wish to test the self-hosting option while running Workspace Platform Starter locally.** + +In code ([client/src/framework/platform/platform.ts](../client/src/framework/platform/platform.ts)) this workspaceAsar setting is specified if enabled (the enabled flag is a Workspace Platform Starter customization). + +```js +await workspacePlatformInit({ + workspaceAsar +}); +``` + +### Outside of Workspace Platform Starter + +If you are looking at adding self-hosting to your own platform then you would still need the serveAsset permission, an appAsset definition and you will need to pass a workspaceAsar object with the alias when you initialize the workspace platform. + +[<- Back to Table Of Contents](../README.md) diff --git a/how-to/workspace-platform-starter/public/manifest.fin.json b/how-to/workspace-platform-starter/public/manifest.fin.json index dc4a1eb9b..1421fae0b 100644 --- a/how-to/workspace-platform-starter/public/manifest.fin.json +++ b/how-to/workspace-platform-starter/public/manifest.fin.json @@ -23,6 +23,7 @@ "launchExternalProcess": true, "terminateExternalProcess": true, "downloadAsset": true, + "serveAsset": true, "openUrlWithBrowser": { "enabled": true, "protocols": ["mailto", "msteams", "tel"] @@ -91,7 +92,8 @@ { "src": "http://localhost:8080/common/assets/workspace_platform.zip", "alias": "self-hosted-workspace-platform", - "version": "20.1.0" + "version": "20.1.0", + "target": "workspace.asar" } ], "customSettings": {