Setting up the Master Server

The Master Server is central to the Hopp installation. It is the Master Server that hosts the Portal Web application and it's required databases.

In general, the Master Server is in change of the central configuration if the Hopp installation. All Execution Servers look to the Master Server for guidance.

Configure Folders

Recommended folder structure on Master Server

• D:\MigFx
  1. Database: Master, Repository and Portal database files here
     • Project: Project Database files here (when setting up a new migration project)
  2. Runtime: OBS: The MigFx Service Account must have full control access to this folder
     • Temp: Director will use this folder for temporary files
  3. Web: Root folder for the IIS default web site

Create Databases

Install Sql Server as per previous guidelines 

NB: Please ensure that all databases are created with the same Sql Server collation.

• Create database MigFx_Master and run setup script MigFx.MasterDb.Setup.sql
• Create database MigFx_Repository and run setup script MigFx.RepositoryDb.Setup.sql
• Create database MigFx_Portal and run setup script MigFx.PortalDb.Setup.sql

Deploy the Portal

Configure IIS

• Use Server Manager to install IIS with this configuration (.NET version numbers in screenshot may be obsolete, please use newest available).
  • Windows Authentication is only required if you plan to use the Windows identity provider in the appsettings.json of the Portal (see below)
  • OBS: Windows Authentication is deprecated and will be removed in future version of Hopp. It is strongly recommended to use either in-app authentication (login form) or External Authentication. See article: Setting up External Authentication
    
    
• Install the .NET Core Hosting Bundle - https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/hosting-bundle
  
  OBS: It is important that the Hosting Bundle is installed after IIS

Authentication

• Anonymous Authentication must be enabled
• Windows Authentication must be Enabled  if you plan to use the Windows identity provider in the appsettings.json of the Portal (see below)
  

Physical Path

It is recommended to set the physical path of the Default Web Site to the Web folder in the MigFx folder hierarchy (see above).

Application Pool

It is preferable to run the Portal Web Application under a separate, dedicated application pool. Suggested name: Hopp.Portal

Configure the App Pool to run under the Hopp Service Account.

Deployment

The Portal can be deployed either as a Web Site or as an Application under a Web Site. The simplest setup is to deploy as a Web Site. You should only consider deploying as an Application if you plan to host other applications next to the Portal on the same Web Site.

• If you are deploying as a Web Site, copy the contents of the migFx folder from the portal.zip file to the physical path of the Default Web Site
  
  
• If you are deploying as an application under the Web Site
  • From the Portal.zip file, copy the migFx folder itself to the physical path of the Default Web Site
  • In IIS Manager, refresh the Default Web Site and right click the migFx folder under the Default Web Site and Convert to Application
     
    
    

Portal settings

All settings for the Portal are in the appsettings.json file in root of the deployment folder. Below is the guidance on how to modify the appsettings in this file. 

Bear in mind that the .NET configuration system will prioritize appsettings defined as environment variables on the machine hosting the Portal over the settings defined in appsettings file. The convention to follow in order to override appsettings with environment variables is quite straight forward: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration.

If the Portal is hosted in a cloud infrastructure, it is typically not an option to edit the appsettings file and the settings are normally defined as environment variables for the cloud app service.

When self-hosting the Portal in IIS the settings can be provided in the appsettings file or optionally as environment variables. If the appsettings file is modified, it will be necessary to preserve these modification when deploying future releases of the Portal.

Edit the appsettings.json file

Be careful when editing json, especially remember that any backslash must be duplicated for the json to parse correctly

1. Set connection strings 
   • MigFxPortal: The MigFx_Portal database created above
   • MigFxMigration: The MigFx_Master database created above
     
     
2. In the Authentication section:
   • Set the PortalUrl to the url that will be used to access the portal
     
     
   • Set IdentityProvider to specify the authentication flow to use for the Portal
     • Windows: The Portal will use the standard NTLM Negotiate flow to obtain an authenticated Windows user from the browser. OBS: Deprecated
       
       
     • Form: The Portal will show an application sign-in form requesting user id and password
       
       
     • External: The Portal will use an external identity provider, for instance Microsoft Entra ID. See separate article Setting up External Authentication on how to configure the Portal for an external identity provider
       
       
3. For first time setup, uncomment and edit the seed user to create the first user in the portal. Once created, the seed user should be commented out or removed from appsettings.json
   
   

Edit the Index.html

OBS: Only if you are deploying as an application under the Web Site. If you are deploying the Portal directly under the Default Web Site, you do not have to edit this file

1. Edit wwwroot/Index.html: Set the base href to migFx: <base href="/migfx/" />

Optional: Create and use a certificate for signing of JSON Web Tokens

By default, the Portal will create and use a transient certificate to sign the JSON Web Tokens of authenticated users. 

This is normally sufficient. However; In some scenarios, it may be required to use a persisted certificate for the signing of JSON Web Tokens. 

In this case, you can create and install a certificate and reference this from appsettings.json:

• The certificate must be created with an RSA private key (Creating RSA Keys using OpenSSL)
  1. These are the openssl command to create a certificate with a 1-year expiry
     
     openssl genrsa -out private-key.pem 3072
     openssl rsa -in private-key.pem -pubout -out public-key.pem
     openssl req -new -x509 -key private-key.pem -out cert.pem -days 360
     openssl pkcs12 -export -inkey private-key.pem -in cert.pem -out cert.pfx
     
     
  2. OBS: Be aware of the expiry of your certificate. You will need to configure a new certificate in time in order to avoid disruptions
     
     
• Install the certificate on the master server. Recommended install location is Local Computer/Personal:
  
  
  
  
• In the Authenticationsection of the appsettings.json:
  1. Uncomment and update the SigningCertificate section to identify the certificate installed above

Optional: Configure file transfers via cloud storage

By default, the Portal and the Hopp Runtime will exchange files using the Temp folder on the master server (see Configure Folders above).

Optionally, this can be changed to the file exchange instead is done using blob storage accessible in Microsoft Azure.

The configuration of using either a local folder or Azure Blob storage is done in the FileStorage section of the Portal appsettings.json file:

"FileStorage": {
  "Provider": "Local", // Local or AzureBlobContainer
  "Local": {
    "Path": "D:\\migFx\\Runtime\\Temp" // Please set the local path to a folder reachable to both the Portal *and* all execution servers
  },
  "AzureBlobContainer": {
    "ConnectionString": "(not set)",
    "ContainerName": "(not set)"
  }
}

Upload Hopp Runtime

Once the Hopp Portal is up and running, you can download the Runtime.zip from the Hopp download page and upload it to the Portal here: