Last updated: 2024-06-26

Host node installation

Prerequisites

The installation of a ShareAspace Host Node has the following prerequisites:

Hardware prerequisites for an Application Server
Software prerequisites for an Application Server

On an Application Server :

Open the port 5001 on the Windows Firewall, like described here.
Make sure a Service Account has been set on the server as described here.

Important

If you are installing a host that needs access to a file vault as a network share, you will need to collect the network address of that share. Usually in the form of:

.\FILESSHARESERVER\folder

Z:\folder (if already mounted on the Application Server where the ShareAspace host node will be installed.)

Also note that the Service Account needs full access to the file vault folder.

ShareAspace Host Server Setup

Installation steps

[1] Run the installer

Run the Host-x.y.z.build.msi to install the ShareAspace Host Node Windows Service

[2] Set the Service Account to run the service

Set the Service Account to run the ShareAspace Nova Host Windows Service
- Open the Services: [Win]+[r] -> Services.msc -> [Enter]
- Find the service named ShareAspace Nova Host
- Right click the service -> Select Properties -> Click Log On -> Provide Username and Password of the Service Account.

Configuration and bootstrap

Open the appsettings.json file found in the installation folder for the Host. By default at: C:\Program Files\Eurostep\ShareAspace\Host\appsettings.json
Set the endpoint URL for the host. This URL must be reachable by the Reverse Proxy.
Configure the location information for the certificate to be used for HTTPS by setting the certificate Subject, Store, and Location.
Configure the AllowedSourceDirectories. This configuration controls the folder paths from where ShareAspace will be allowed to pick files from when instructed to so via the bulk upload API.
Read more about the checkpoint in the Failover configuration.

{
  "Kestrel": {
    "Endpoints": {
      "https": {
        "url": "https://host.machine.net:5001"
      }
    },
    "checkpoint": {
      "enableRestoreMode": false,
      "checkpointId": "*"
    },
    "Certificates": {
      "Default": {
        "Subject": "[Ceritificate subject]",
        "Store": "[Ceritificate store]",
        "Location": "[Ceritificate location]"
      }
    },
    "BulkFileUploadAPI": {
      "AllowedSourceDirectories": [ "C:\\example\\path" ] // will allow subfolders too
    }
  }
}

The bootstrap tool named Eurostep.SAS.Bootstrap.exe is used to bootstrap the node itself and uses a json file format to indicate the different bootstrap parameters. There is a sample configuration file included in the install package for the host named bootstrap_host.json.

Host Bootstrap Configuration file

baseStorePath - Path to where on disk the host will store the transient database. The path is relative to the installation location of the host unless explicitly defined.
baseFileSystemStorePath - File vault path to where on disk the host will store the blob storage for files uploaded to ShareAspace. The path can be relative to the installation location of the host or a network share. This folder is also used for storing checkpoints when running in failover mode.
serverAddresses - The URI and the Port where the host can be reached.
systemPath - The path where the host will store system specific files.

Important

In a multiple machine deployment scenario, the store must be set to be on the same machine as the host machine.

Example

{
  "baseStorePath": ".\\Storage",
  "baseFileSystemStorePath": ".\\FileSystem",
  "serverAddresses": [
    "https://host.machine.net:5000/"
  ],
  "systemPath":  ".\\System"
}

Warning

In a JSON file, backslashes used in path have to be escaped with a backslash: "\\"

Note

When installing a single machine setup of ShareAspace there is no need for the FQDN (Fully Qualified Domain Name) for the host (since it should not be exposed). Instead localhost can be used, provided it is supported by the certificate.

Service host configuration file
If you use a system path other than its default path, you need to add it to the configuration file named Eurostep.SAS.ServiceHost.dll.config.

Example

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.1" />
  </startup>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
        <bindingRedirect oldVersion="0.0.0.0-4.5.0.0" newVersion="4.5.0.0" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
  <appSettings>
    <add key="systemPath" value="[System path]" />
  </appSettings>
</configuration>

Note

If you use the default system path, you don't need to edit Eurostep.SAS.ServiceHost.dll.config.

Generate symmetric signing keys

Some components require the use of a symmetric key to sign a value. The key is used for security reasons. The same key should not be used for multiple installations.

There is a tool that is included in the installation of the ShareAspace Host that can be used for generating random keys.

Open Windows PowerShell
Navigate to the tools folder under the installation folder of the IdentityServer
Execute the program Eurostep.SAS.Tools.SymmetricKeyGen.exe (normally at C:\Program Files\Eurostep\ShareAspace\Host) to get a symmetric Signing Key

It is also possible to generate the key through PowerShell; make sure the key is 64 bit. Below is an example how to generate a 64 bit random key using PowerShell.

Download generate-symmetric-key.ps1

[!code-ps[generate-symmetric-key.ps1](nova-host/_static/generate-symmetric-key.ps1#L27-)]

Failover configuration

In case the installed ShareAspace Host is intended to run in with failover support, the checkpoint section of the file named appsettings.json (included in the install package of the host) needs to be configured:

Configuration template:

  "checkpoint": {
    "enableRestoreMode": "_ENABLERESTOREMODE_",
    "checkpointId": "_CHECKPOINTID_",
    "enableAutomaticCheckpoints": "_ENABLEAUTOMATICCHECKPOINTS_",
    "checkpointLogSizeThreshold": "_CHECKPOINTLOGSIZETHRESHOLD_",
    "createCheckpointOnCollectionBootstrap": "_CREATECHECKPOINTONCOLLECTIONBOOTSTRAP_"
  }

Identifier	Description
`enableRestoreMode`	Boolean true/false, if true the host node will be in "standby" for a restore signal.
`checkpointId`	Id on checkpoint to restore from, use `*` for latest.
`enableAutomaticCheckpoints`	Boolean true/false, if true the automatic checkpointing functionality is activated.
`checkpointLogSizeThreshold`	The maximum size (in bytes) of journal files before a new automatic checkpoint is created. Default value is `314572800` (300MB). Only applicable if the checkpointing is activated (i.e. `enableAutomaticCheckpoints` = "`true`")
`createCheckpointOnCollectionBootstrap`	Boolean true/false, if true the host will create the first automatic checkpoint when the collection is created. Only applicable if the checkpointing is activated (i.e. `enableAutomaticCheckpoints` = "`true`")

Example:

  "checkpoint": {
    "enableRestoreMode": "true",
    "checkpointId": "*",
    "enableAutomaticCheckpoints": "true",
    "checkpointLogSizeThreshold": "314572800",
    "createCheckpointOnCollectionBootstrap": "true"
  }

The host node that will start as the primary node need the following configurationPrimary node configuration as follows.

"checkpoint": {
    "enableRestoreMode": false,
    "checkpointId": "*"
}

Secondary node(s) used for failover should enable the checkpoint restore mode on startup, this is achieved by setting the enableRestoreMode to true.

"checkpoint": {
    "enableRestoreMode": true,
    "checkpointId": "*"
}

Create checkpoint manually

It is possible to trigger the creation of a checkpoint manually using the REST API.

Create-Checkpoint.ps1

param (
[Parameter(Mandatory=$true)]
[string]$NovaHost,
[Parameter(Mandatory=$true)]
[string]$SnapshotApiKey
)

Function Get-BearerToken ($pathAndQuery)
{
    $encodedPath = [Text.Encoding]::ASCII.GetBytes($pathAndQuery)
    $hmacsha = New-Object System.Security.Cryptography.HMACSHA512
    $hmacsha.key = [Convert]::FromBase64String($SnapshotApiKey)
    $bearerToken = $hmacsha.ComputeHash($encodedPath)
    $bearerToken = [Convert]::ToBase64String($bearerToken)
    $bearerToken = $bearerToken.Split('=')[0]
    $bearerToken = $bearerToken.Replace('+', '-')
    $bearerToken = $bearerToken.Replace('/', '_')
    Return $bearerToken
}

$failed = $false

Try
{
    $path = "/admin/checkpoint/create"
    $uri = "{0}{1}" -f $NovaHost.TrimEnd('/'), $path
    $query = ""
    $pathAndQuery = "{0}{1}" -f $path, $query
    $bearerToken = Get-BearerToken($pathAndQuery)
    $bearerHeader = @{ "Authorization" = ("Bearer", $bearerToken -join " ") }
    $checkpointUri = "{0}{1}" -f $uri, $Query
    Invoke-RestMethod -Method Post -Uri $checkpointUri -ContentType "application/json" -Headers $bearerHeader
}
Catch
{
    Write-Error "An error occured while scheduling checkpoint"
    Write-Error $_.Exception.Message
    $failed = $true
}
Finally
{
    if (-Not $failed)
    {
        Write-Host "Done."
    }
}

Example:

.\Create-Checkpoint.ps1 -NovaHost https://FQDN:5001 -SnapshotApiKey $key

The checkpoint and journal files will be written to the configured file vault folder (under the checkpoint folder).

/FileVault/checkpoint
  |-- Checkpoint-0000000001
  |-- collection/000000001/checkpoint.journal
  |-- space/space1/000000001/checkpoint.journal
  |-- space/space1/Index/IdNameIndex/000000001/checkpoint.journal

Checkpoint-X -- checkpoint file
X/checkpoint.journal -- journal file for checkpoint "X"

Folder structure follows the same pattern as the ShareAspace data storage.

Folder/File	Description
/FileVault/checkpoint/	Checkpoint store base path
-- Checkpoint-0000000001	Host-wide checkpoint file. (1)
-- collection/000000001/checkpoint.journal	Checkpoint journal for the collection
-- space/space1/000000001/checkpoint.journal	Checkpoint journal for a space
-- space/space1/Index/IdNameIndex/000000001/checkpoint.journal	Checkpoint journal for an individual index

(1) : The checkpoint files are ZIP file and can be of 2 sorts:

collection wide checkpoints taken automatically (if the host is set to take automatic checkpoints)
space specific checkpoints taken manually via the API

Table of Contents

Host node installation

Prerequisites

Important

Installation steps

[1] Run the installer

[2] Set the Service Account to run the service

Configuration and bootstrap

Important

Warning

Note

Note

Generate symmetric signing keys

Failover configuration

Create checkpoint manually