Table of Contents

Settings Snapshot

Introduction

The Jubilant installer script copies files form the installer folder into the required place on the file system. It is possible to update the settings files in the installer folder so that when they are copied into the runtime location, the settings files are what are required.

There are two scripts that help you manage this process. One script gathers the current installation's settings into zip file (a snapshot). Another script takes the settings contained in a snapshot (zip) and applies them to the installation folder.

Once a snapshot has been applied to a installation folder, running JubilantInstaller.ps1 as Admin will install Jubilant with the settings that were applied from the snapshot. There are special considerations around certificates explained below.

JubilantSettingsSnapshot.ps1

Running JubilantSettingsSnapshot.ps1 as Admin creates a zip file containing all the settings configured in the active local install. This file is named SettingsSnapshot-{name of machine}.zip.

Warning

This deletes any existing snapshot file of the same name.

JubilantUpdateInstallerFromSnapshot.ps1

Running JubilantUpdateInstallerFromSnapshot.ps1 as Admin looks for an adjacent SettingsSnapshot-{name of machine_}.zip file to work with. When it is found, it unzips the file, and copies them over the existing files in the installer.

This local copy of the installer is now altered. Copying this installer on to any other machine will install Jubilant with those settings. There is no need to copy the SnapShot file, as the installer has been permanently modified to only contain the applied settings.

GRPC Connection Point Certificates

New certificates are generated by the installer unless a Certificates.json file is placed in the {installer folder}\Certificates\ folder.

JubilantUpdateInstallerFromSnapshot.ps1 extracts the currently installed thumbprints for the relevant certificates.

The installer replaces the DefaultCertificates section in process configuration files with the thumbprints of newly generated certificates or with the thumbprints provided in the Certificates.json file.

Note

It is important that the certificates that match Certificates.json file are installed on the target Windows Server for the installer script to run. If the matching certificates are not found, the installation will not proceed.

Exporting Certificates for Use on Another Machine

For a certificates.json file generated from a snapshot to function correctly, the certificates must be manually copied form the source server to the target server. The certificates must be exported as a password protected PFX file including private key and extended properties.

One the source server, launch the local Windows certificate manager, locate the appropriate certificates, right click, select all tasks, and then export.

On the target server, install the exported certificates back into the same local machine location as the source machine.

New Certificates

It is possible not to reuse the existing certificates on a new server simply by deleting the Certificates folder in the installer folder. The installer will then generate new certificates.

Structure of a Snapshot file.

Snapshot Source Folder is relative to the top level "SettingsSnapshot" folder inside the snapshot zip.

The Target Installer Folder is relative to the top level installer folder (where the PowerShell scripts are).

ProgramData\WebTerminalHub

Snapshot
Source Folder		 File Target
Installer Folder
Certificates Certificates.json Certificates
Program Files\HostScreenServer\Definitions {host-definition}.json Definitions
Program Files\HostScreenServer hostscreen-server.serversettings.json hostscreen.server
Program Files\LoggingServer logging-server.settings.json Logging.service
Program Files\LogViewer\web\hub appsettings.json Log.Viewer.Hub
Program Files\ManagementConsole\web\hub appsettings.json Management.Console.Hub
Program Files\Server\LicenceRepository Licences.json Licenses
Program Files\Server appsettings.json Server.service
Program Files\WebTerminal\web\hub appsettings.json Web-terminal-emulator.hub
Program Files\WebTerminal\web\settings colourmappings.json Web-terminal-emulator.web\settings
Program Files\WebTerminal\web\settings config.json Web-terminal-emulator.web\settings
Program Files\WebTerminal\web\settings keyboardlayouts.json Web-terminal-emulator.web\settings
Program Files\WebTerminal\web\settings keymappings.json Web-terminal-emulator.web\settings
Program Files\WebTerminal\web\settings keys.json Web-terminal-emulator.web\settings
Program Files\WebTerminal\web\settings settings.json Web-terminal-emulator.web\settings
ProgramData\WebTerminalHub WebTerminalSettings.json Preserve\WebTerminal\Web\Hub

Help

Customised help is not included in the snapshot. It must be manually copied into the correct location in the installer.

Installed Source Folder File Destination Installer Folder
Program Files\Flynet\Jubilant\WebTerminal\web\help Custom help files Web-terminal-emulator.web\help

Fresh Install Process

The installer script JubilantInstaller.ps1 installs the installation files that have been updated by the JubilantUpdateInstallerFromSnapshot.ps1.

Running JubilantInstaller.ps1 on a clean Windows Server will install a version of Jubilant with all the custom settings. As the snapshot has been applied to the installer files, the snapshot zip file is not needed for install.

Jubilant Installer Parameters

The JubilantInstaller.ps1 script has two optional parameters.

installRoot

A string path to the location where Jubilant must be installed.

Default is C:\Program Files\Flynet\Jubilant\.

websiteToUse

A string name of the IIS Web Site in which the installer must add the Jubilant web apps.

Default is Default Web Site.

Update Process

  1. Create a version of the installer that has been updated with customised settings using JubilantUpdateInstallerFromSnapshot.ps1.
  2. Reusing Certificates?
    • Yes: Export Certificates from Source server and import on to Target Server.
    • No: Remove Certificates Folder from install location.
  3. Run JubilantUninstall.ps1 as Admin
  4. Run JubilantInstaller.ps1 as Admin

Flow Diagram

flowchart
    jubilantSettingsSnapshot[JubilantSettingsSnapshot.ps1] -->|Installed Settings|settingsSnapshotZip["`SettingsSnapshot-{_machine-name_}.zip`"]
    settingsSnapshotZip --> jubilantUpdateInstallerFromSnapshot[JubilantUpdateInstallerFromSnapshot.ps1]
    jubilantUpdateInstallerFromSnapshot -->|Snapshot Settings|installerFiles[Installer Files] --> reusingCertificates

    reusingCertificates{Reusing
        Certificates?} --> |Yes| exportImportCertificates[Export Certificates
            from Source server
            and import on
            to Target Server] --> updateOrFreshInstall
    reusingCertificates --> |No| remoteCertificates[Remove Certificates
        Folder from install
        location] --> updateOrFreshInstall

    updateOrFreshInstall{Update or
        Fresh Install?} -->|Update|updateUninstall[JubilantUninstall.ps1]
    updateOrFreshInstall -->|Fresh|jubilantInstaller[JubilantInstaller.ps1]
    
    updateUninstall --> jubilantInstaller
    
    jubilantInstaller -->|Settings|installed[Installed]