Last updated: 10/15/2026

ShareAspace Host installation

Prerequisites

The installation of a ShareAspace Host has the following prerequisites:

Hardware prerequisites for an Application server.
Software prerequisites for an Application server.

On the Application server:

Open ports in the Windows Firewall, as described here.
- Default ports: 5001 for the REST API, and 5002 for services (used by new Web).
Make sure a Service Account has been set on the server as described here.

Important

If the Host node requires access to a File Vault hosted on a network share, ensure that the network path is available.

Examples:

\\FILESHARESERVER\folder
Z:\folder (if the share is mapped on the Application Server)

The Service Account must have full control permissions on the File Vault folder.

ShareAspace Host Server Setup

Installation steps

Step 1: Run the installer

Run the Host.msi installer to install the ShareAspace Host Windows Service.

Step 2: Configure the service account

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, and provide the username and password of the Service Account.

Step 3: Configure the host

See the Configuration section and, if applicable, the Failover configuration.

Step 4: Start the host

Start the ShareAspace Nova Host Windows Service and verify that the API root endpoint is accessible.

GET https://host.machine.net:5001

Configuration

Open the appsettings.json file located in the ShareAspace Host installation folder.

By default: C:\Program Files\Eurostep\ShareAspace\Host\appsettings.json

Host endpoints

Configure the host endpoint URL (Kestrel.Endpoints.https.url). This URL must be reachable by the Reverse Proxy.
Configure the RpcHost URL. This URL must be reachable by the Web (new) application (if used).

{
  ...
  "Kestrel": {
    "Endpoints": {
      "https": {
        "url": "https://host.machine.net:5001"
      }
    },
    ...
  },
  "RpcHost": {
    "Endpoints": {
      "https": {
        "Url": "https://host.machine.net:5002",
        ...
      }
    },
    ...
  },
  ...
}

Host certificates

Configure the location information for the certificate(s) to be used for HTTPS by setting the certificate Subject, Store, and Location.
For mTLS configuration, see mTLS.

{
  ...
  "Kestrel": {
    ...
    "Certificates": {
      "Default": {
        "Subject": "[Certificate subject]",
        "Store": "[Certificate store]",
        "Location": "[Certificate location]"
      }
    },
    ...
  },
  "RpcHost": {
    ...
    "Certificates": {
      "Default": {
        "Subject": "[Certificate subject]",
        "Store": "[Certificate store]",
        "Location": "[Certificate location]",
        "AllowInvalid": false
      }
    }
  },
  ...
}

Storage configuration

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.

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

Bulk upload configuration

Configure AllowedSourceDirectories. This configuration controls the folders from which ShareAspace can pick files when instructed to do so via the bulk upload API. This includes all subfolders under each specified root.

{
  ...
  "BulkFileUploadAPI": {
    "AllowedSourceDirectories": [ "C:\\example\\path" ]
  }
}

External endpoints

Configure ShareAspace.Endpoints.BaseUri. In a normal setup, this is the public-facing URL for the ShareAspace reverse proxy.

{
  ...
  "ShareAspace": {
    ...,
    "Endpoints": {
      "BaseUri": "https://gateway.machine.net/api"
    },
    ...
  }
}

Generate symmetric signing keys

Some components require 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 included in the ShareAspace Host installation that can be used to generate random keys.

Open Windows PowerShell
Execute 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. Ensure the key is of sufficient length (typically 64 bytes). Below is an example of how to generate a 64-byte random key using PowerShell.

Download generate-symmetric-key.ps1

function generateSymmetricKey($length){
    $bytes  = New-Object Byte[] $length
    $generator = New-Object System.Security.Cryptography.RNGCryptoServiceProvider
    $generator.GetBytes($bytes)
    $generator.Dispose()
    return [Convert]::ToBase64String($bytes)
}

generateSymmetricKey 64 | Write-Host

Failover configuration

To enable failover, configure the ShareAspace.Checkpoint section in appsettings.json.

{
  ...
  "ShareAspace": {
    "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 primary node should use the following configuration:

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

Secondary node(s) used for failover should enable Checkpoint restore mode on startup by setting 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 occurred 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 files and are one of two types:

Collection-wide checkpoints taken automatically (if the host is set to take automatic checkpoints)
Space-specific checkpoints taken manually through the API

OpenTelemetry configuration

The ShareAspace Host component supports OpenTelemetry (OTEL) for logging, metrics, and tracing.

Configuration is performed using configuration variables, for example:

{
  "OTEL_SERVICE_NAME": "ShareAspace",
  "OTEL_EXPORTER_OTLP_ENDPOINT": "https://host.example.com:4317",
  "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc"
}

Additional OTEL configuration options are available and are shared across all ShareAspace components.

See: OpenTelemetry logging.

Table of Contents