Last updated: 2024-11-14

Bootstrap host collection

Bootstrap with tool

The bootstrap tool named Eurostep.SAS.CollectionBootstrap.exe is used:

for bootstrapping a ShareAspace Collection on top of a ShareAspace Host Node.
for triggering a manual restore of a checkpoint on to a ShareAspace Host Node.

The configuration file Eurostep.SAS.CollectionBootstrap.dll.config controls the execution of the tool mentioned above:

host - The URL of ShareAspace Host Node to add a collection to or to link to a cluster
file- The file configuration file for the action. (e.g. bootstrap_collection.json)
action
- bootstrap for bootstrapping a new collection on to the host.
- restore for triggering a checkpoint restore on to the host.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="host" value="https://host.machine.net:5001"/>
    <add key="file" value="bootstrap_collection.json"/>
    <add key="action" value="bootstrap"/>
  </appSettings>
</configuration>

When the configuration parameters are set, execute the Eurostep.SAS.CollectionBootstrap.exe tool from a command prompt or a Windows PowerShell.

Note

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

C:\Program Files\Eurostep\ShareAspace\Host\> Eurostep.SAS.CollectionBootstrap.exe

There is a sample 'json' files included in the installation folder of the host named bootstrap_collection.json.

Tip

When bootstrapping the collection, the collection bootstrap tool will generate and return a Personal access token (PAT) for the collection administrator. This PAT can be used for further setup scripts during the setup process.

Initiating a collection

To bootstrap the collection of a ShareAspace Host Node, the Collection Bootstrap tool needs to be run with a json file format according to the structure given as example in the file bootstrap_collection.json and indicated in the Eurostep.SAS.CollectionBootstrap.dll.config configuration file.

To populate this collection bootstrap configuration json file you will need to collect several information first:

All the APIs signing keys generated when installing the ShareAspace Host.
The fully qualified domain name (ex: webserver.machine.net) of the ShareAspace Web Client
The ShareAspace Collection default administrator credentials : email address and password (The password will need to be encoded and this can be done with one of the tool provided in installation kit ShareAspace).
Other users credentials : email addresses and password (The password will need to be encoded and this can be done with one of the tool provided in installation kit ShareAspace).
The list of GUI out-of-the-box modules that should be activated as well as custom GUI modules

The structure of the configuration file bootstrap_collection.json contains the following sections:

API keys

In this section we will add the following apiKeys.

  "apiKeys": [
    {
      "id": "TaskUploadAPI",
      "key": "PNPpeRwe7XBleg...erYJRlMzV1Kzt8/LHA=="
    },
    {
      "id": "AdministrationAPI",
      "key": "mDkbE5471+4m/Ep...MK/Uf9gvBhJYi/jkQ=="
    },
    {
      "id": "SnapshotAPI",
      "key": "XMztXdXRFQsH0MH...hHdGnyeEXZyYJn7vg=="
    },
    {
      "id":  "LicenseCommunicationAPI",
      "key":  "+vAC0QP5ASZvQV...Nhi9BP8ntLItBoEciA=="
    }
  ]

The SymmetricKey key should be generated as described in the section Generate Symmetric Signing Keys.

OpenID Connect Trust

See the OpenID Connect documentation.

Authorization

The authorization section defines:

userSigningKeyLifeTime - The time span for the rotation of the signing key that will be used when signing JSON Web Tokens (JWT) that ShareAspace issues.
tokenLifeTime - The life time of generated JSON Web Tokens (JWT) that ShareAspace issues.

"authorization": {
  "userSigningKeyLifeTime": "90.00:00:00",
  "tokenLifeTime": "30.00:00:00"
}

DAYS.HOURS.MINUTES.SECONDS

Collection users

This section of the bootstrap bootstrap_collection.json sets up collection users. It is required to setup at least one user. It is also required that one of the users has the collectionAdministrator value set to true.

It is also required that there is an instance of a user in the users array with a matching email address.

Note

Note that there can be more than one Collection Administrator.

Example

"collectionUsers": [
    {
        "email": "admin@eurostep.com",
        "avatar": "",
        "introduction": "This is the updated bio.",
        "firstName": "Collection",
        "lastName": "Admin",
        "displayName": "Collection Admin",
        "collectionAdministrator": true
    }
],
"users": [
  {
    "email": "admin@eurostep.com"
  }
],

Modules

This section of the bootstrap bootstrap_collection.json sets up what modules to activate in the collection.

Example

"modules": [
    ...
    {
      "moduleType": "Ordinary",
      "id": "ProjectStateManagement",
      "name": "Project state management"
    },
    ...
  ]

Nova endpoint

This section of the bootstrap bootstrap_collection.json is used to set up the URI of where the reverse proxy is located.

The nova endpoint URI is used by e.g. the external extensions and in the liquid scripting language.

Example

"novaEndpoint": {
  "baseUri": "https://gateway.machine.net/api"
}

If extensions are located on the same machine as the host and the reverse proxy then https://host.machine.net:5001 can be used as value. It is however recommended to run external extensions on separate machines i.e. the reverse proxy URL should be used.

Invite

This section of the bootstrap bootstrap_collection.json sets up the invite email fromAddress and the configuration to the authorizationServer and the identityServer for the invite email flow.

Example

"invite": {
    "fromAddress": "admin@eurostep.com",
    "authorizationServer": "https://authorizationserver.machine.net/DeveloperLogin",
    "identityServer": "https://identityserver.machine.net/DeveloperLogin",
    "disable": true
}

Tip

To disable the out of the box invite emails set the disable flag to true. The default value is false. This would typically be turned off in a scenario where there is an event based configuration for custom invite emails.

Time zone

This section of the bootstrap bootstrap_collection.json sets up the default time zone.

Example

"timeZone": "Europe/London"

Languages

This section of the bootstrap bootstrap_collection.json sets up the culture settings.

Example

"languages": [
{
    "key": "en",
    "isDefault": true,
    "value": "English (United States)",
    "culture": "en-us"
}

Licence

This section of the bootstrap bootstrap_collection.json sets up a licence key. This step is optional, i.e. the licence can be applied at a later stage via the REST APIs or via the Collection Administration User Interface.

To extract the licence key from a licence file *.olrp, open the file in a text editor. Within the file you will see a Base64 string. Copy this string an place it in the value for licenseKey in the bootstrap_collection.json file.

Example

"licenseKey":  "eyJ0eXAiOiJKV1Q...bh0j67qzxYVUy4ptN2F2pKDaz1KXo3mPcJspCDoa5WEg"

Request limits

Controls the request limit (the number of requests a user can make of the system in any given time span) configuration of the system. The request limiter is using the Sliding window algorithm and is by default configured to 2000 requests over 5min per user.

If a user hits this limit either by requests executed directly by the user or indirectly by an extension acting on behalf of the user the ShareAspace API will respond with the status code 429, Too Many Requests.

The request limit is optionally configurable.

  "requestRatePolicy": {
    "samplingWindowSize": 5,
    "requestLimit": 2000
  }

The request limit can be set and/or changed via the administration API at a later time.

GET /admin/requestRatePolicy HTTP/1.1
Accept: application/json
Authorization: Basic bX...

PUT /admin/requestRatePolicy HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic bX...
SAs-UOIVersion: 3

Note

The ShareAspace Host Service must be restarted for an updated configuration to take effect.

function GetAuthorizationHeader ($key, $path){
    $encodedPath = [Text.Encoding]::ASCII.GetBytes($path)
    $sha = New-Object System.Security.Cryptography.HMACSHA512
    $sha.key = [Convert]::FromBase64String($key)
    $hash = $sha.ComputeHash($encodedPath)
    $hashString = [Convert]::ToBase64String($hash)
    $bearerToken = $hashString.Split('=')[0]
    $bearerToken = $bearerToken.Replace('+', '-')
    $bearerToken = $bearerToken.Replace('/', '_')
    return @{"Authorization" = ("Bearer", $bearerToken -join " ")}
}

$adminAPIkey = "jgO...=="
$hostUrl = "https://server:5001"
$path = "/admin/requestRatePolicy"

$uri = "$hostUrl + $path
$headers = GetAuthorizationHeader $adminAPIkey $path

$response = Invoke-RestMethod -Method Get -Uri $uri -ContentType "application/json" -Headers $headers

$response.data.requestLimit = 7
$response.data.samplingWindowSize = 20000

$body = $response.data | ConvertTo-Json
$headers.Add("SAs-UOIVersion", $response.version)

Invoke-RestMethod -Method Put $uri -ContentType "application/json" -Headers $headers -Body $body

Personal access token

Configures the from email address that will be used for emails related to personal access tokens notifications.

Emails will be sent:

when a personal access token is created (to the user that created it).
2 days before a personal access token is about to expire.

{
    ...
    "personalAccessToken": {
        "fromAddress": "_FROM_ADDRESS_"
    }
    ...
}

Manual failover restore

1 - Make sure that the host bootstrap has been executed using host bootstrap settings with the restore mode configuration active.

2 - Change the Eurostep.SAS.CollectionBootstrap.dll.config action to restore, and make sure the host value points to the node where the checkpoint should be restored:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="host" value="https://FQDN:5001"/>
    <add key="action" value="restore"/>
  </appSettings>
</configuration>

3 - Start Eurostep.SAS.ServiceHost process as usual.

Start-Service Eurostep.SAS.ServiceHost

This time the host will start in a restore mode. It will listen for a POST request on the /system/restore route.

4 - Finally, run Eurostep.SAS.CollectionBootstrap.exe to start the checkpoint restore.

.\Eurostep.SAS.CollectionBootstrap.exe

The host will restore the storages found in the checkpoint and replay the checkpoint journal files. Once the restore is complete, the host will exit the restore mode, and start itself in "live" mode.

Note

The checkpoint restore is a background task. Eurostep.SAS.CollectionBootstrap.exe will report Done once it has sent the signal to start the restore. Done does not indicate that the restore is completed.

Table of Contents

Bootstrap host collection

Bootstrap with tool

Note

Tip

Initiating a collection

API keys

OpenID Connect Trust

Authorization

Collection users

Note

Modules

Nova endpoint

Invite

Tip

Time zone

Languages

Licence

Request limits

Note

Personal access token

Manual failover restore

Note