Last updated: 12/20/2025

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.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

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.
Configure the ShareAspace.Endpoints.BaseUri, this is in a normal setup the public facing URL for the ShareAspace reverse proxy.
Configure the ShareAspace.Storage.Path.
- If only Base is provided, e.g. F:\\, ShareAspace will default:
  - FileVault to F:\\FileVault
  - Logging to F:\\Logging
  - Storage to F:\\Storage
- All of these can be overridden by adding them to the 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
    }
  },
  "RpcHost": {
    "Endpoints": {
      "https": {
        "Url": "__RPCHOSTURI__",
        "ClientCertificateMode": "NoCertificate"
      }
    },
    "Certificates": {
      "Default": {
        "Store": "My",
        "Location": "LocalMachine",
        "Subject": "esaz112",
        "AllowInvalid": false
      }
    }
  },
  "ShareAspace": {
    "Storage": {
      "Path": {
        "Base": "F:\\"
      }
    },
    "Endpoints": {
      "BaseUri": "https://gateway.machine.net/api"
    }
  }
}

{
  ...
  "ShareAspace": {
    "Storage": {
      "Path": {
        "Base": "F:\\",
        "FileVault": "D:\\FILEVAULT-OVERRIDE",
        "Logging": "F:\\Logging-OVERRIDE",
        "Storage": "F:\\Storage-OVERRIDE",
      }
    },
    ...
  }
}

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