Repository backup

Endpoints

Backup and restore functionality is available through two API endpoints provided by the Studio server. Authentication requires a Bearer token, which can be requested from Keycloak as described here.

Create repository backup

GET http://localhost:170/Studio/Server/Depot/api/v1/admin/backup
Authorization: Bearer {{ token }}

The response is a binary stream representing a ZIP archive that should be written to a file.

It is recommended that the file that is created by running the tool is not considered as primary backup, but replicated on a different machine and that backups from multiple days are retained! As such, we strongly advise to copy the resulting file somewhere safe and to avoid overwriting the backup of the prior seven days.

Restore repository backup

POST http://localhost:170/Studio/Server/Depot/api/v1/admin/backup
Authorization: Bearer {{ token }}

The request body needs to be a binary stream representing a repository backup ZIP archive.

A restore operation only affects the repositories that are present within the backup. Such repositories are replaced with the contents of the backup file, which cannot be undone. Repositories that are stored in the Studio Server but not present in the backup are kept as is.

PowerShell script

The following PowerShell script can be used to automate the creation of backups. The script serves as an example and can be modified as desired. The authentication scheme that is used requests a Bearer token using the client_credentials grant, please refer to Keycloak configuration#Clients on how to create a client that supports service accounts.

<#
.SYNOPSIS
Backup and restore Blueriq Studio server environments

.DESCRIPTION
Backup
    .\backup.ps1 backup -Environment http://localhost:170 -BackupFile ./backup-$((Get-Date).ToString("yyyyMMdd-HHmmss")).zip

Restore
    .\backup.ps1 restore -Environment http://localhost:170
#>
param(
  [Parameter(Mandatory = $True, Position = 0)]
  [ValidateSet('backup', 'restore')]
  [string]
  $Command,

  [Parameter()]
  [ValidateNotNullOrEmpty()]
  [string]
  $Environment = 'http://localhost:170',

  [Parameter(Mandatory = $True)]
  [ValidateNotNullOrEmpty()]
  [string]
  $BackupFile,

  [Parameter()]
  [ValidateNotNullOrEmpty()]
  [string]
  $Client = 'backup',

  [Parameter(Mandatory = $True)]
  [ValidateNotNullOrEmpty()]
  [string]
  $ClientSecret
)

$ProgressPreference = 'SilentlyContinue'
$ErrorActionPreference = 'Stop'

function AcquireToken() {
  Write-Host "Authenticating"

  try {
    $Response = Invoke-RestMethod `
      -Method POST `
      -Uri "${Environment}/Keycloak/realms/BlueriqStudio17/protocol/openid-connect/token" `
      -Body @{
      grant_type = 'client_credentials';
      client_id = $Client;
      client_secret = $ClientSecret;
    } `

    $AccessToken = $Response.access_token
    return "Bearer $AccessToken"
  } catch {
    Write-Error "Obtaining token from ${Environment} failed: $_"
  }
}

function Command-Backup() {
  Write-Host "Writing backup from $Environment to $BackupFile"

  try {
    Invoke-RestMethod `
      -Method GET `
      -Uri "${Environment}/Studio/Server/depot/api/v1/admin/backup" `
      -Headers @{ 'Authorization' = $Token } `
      -OutFile $BackupFile | Out-Null
  } catch {
    Write-Error "Creating backup for ${Environment} failed: $_"
  }
}

function Command-Restore() {
  Write-Host "Restoring backup $BackupFile to $Environment"

  try {
    Invoke-RestMethod `
      -Method POST `
      -Uri "${Environment}/Studio/Server/depot/api/v1/admin/backup" `
      -Headers @{ 'Authorization' = $Token } `
      -ContentType 'application/zip' `
      -InFile $BackupFile | Out-Null
  } catch {
    Write-Error "Restoring backup to ${Environment} failed: $_"
  }
}

$Token = AcquireToken

switch ($Command)
{
  'backup' { Command-Backup }
  'restore' { Command-Restore }
}

Configuration backup

A configuration backup consists of all user roles and their associated access matrices, and all role mappings present on a Studio server. Please note that the Studio's StudioService.dll.config file is not included in this backup. A configuration backup can be created and restored using the following endpoints. Note that restoring a configuration backup will overwrite all current user roles and role mappings. Authentication requires a Bearer token, which can be requested from Keycloak as described here.

Endpoints

Create configuration backup

GET http://localhost:170/Studio/Server/Depot/api/v1/admin/configuration
Authorization: Bearer {{ token }}

The response is a binary stream representing a ZIP archive that should be written to a file.

Restore configuration backup

POST http://localhost:170/Studio/Server/Depot/api/v1/admin/configuration
Authorization: Bearer {{ token }}
Content-Type: application/octet-stream

The request body needs to be a binary stream representing a configuration backup ZIP archive.

Restoring the configuration cannot be undone. Consider creating a backup of the current situation before restoring another backup.