Loading...
Area: Episerver DXC Service
Applies to versions: Not applicable

How to deploy using Deployment API

This topic describes how to deploy using the Deployment API for Episerver Digital Experience Service, and the Powershell module provided with the API.

EpiCloud Powershell module

To simplify usage of the deployment API, a PowerShell module, EpiCloud, is available which contains the following cmdlets:

  • Connect-EpiCloud.
    Simplifies overall cmdlet usage by supplying the required credentials to other commands in the module.
  • Add-EpiDeploymentPackage.
    Upload a deployment package to the DXC-S environment to use for deployments; requires the Azure PowerShell modules (Azure.Storage or Az.Storage) to run.
  • Get-EpiDeploymentPackageLocation.
    Returns a SAS link to upload deployment packages (using Add-EpiDeploymentPackage or other methods).
  • Start-EpiDeployment.
    Starts a new deployment.
  • Get-EpiDeployment.
    Fetches information about deployments (ongoing or finished).
  • Complete-EpiDeployment.
    Completes an existing deployment, which is in the "verification" stage. (Same as Complete/Go Live in the management portal.)
  • Reset-EpiDeployment.
    Resets a deployment. (Same as Reset in the management portal.) Note that this will not restore the database (also same as in the management portal).

All cmdlets have built-in help that you can access in the PowerShell console using the Get-Help cmdlet. This help includes examples on how to use the commands and descriptions on all parameters. For example:

Get-Help Start-EpiDeployment -Full

Or if you want a graphical interface to access the help:

Get-Help Start-EpiDeployment -ShowWindow

Installation

The module is available at the PowerShell Gallery. To install it, open PowerShell and run the following command:

Install-Module -Name EpiCloud -Scope CurrentUser

This installs the module for the current user (and does not require Administrator privileges). For instructions about using the PowerShell Gallery and the related PowerShell cmdlets for managing modules and scripts, see Microsoft's documentation.

Sample usage

If you install the module from the PowerShell Gallery, the module will be loaded automatically when you call a cmdlet. To explicitly import the module you can use the following command:

Import-Module EpiCloud

Optionally, you can add your credentials to the current PowerShell scope by calling the Connect-EpiCloud cmdlet with your ClientKey and ClientSecret after which you do not have to specify the ClientKey or ClientSecret for any other of the cmdlets in the module during the session.

Connect-EpiCloud -ClientKey <ClientKey> -ClientSecret <ClientSecret>

To upload a code package to your DXC-S project, call Get-EpiDeploymentPackageLocation to get the SAS link where the package should be uploaded, and then call Add-EpiDeploymentPackage to upload that package, as follows.

$saslink = Get-EpiDeploymentPackageLocation -ProjectId 2a561398-d517-4634-9bc4-aab5008a8e1a
Add-EpiDeploymentPackage -SasUrl $saslink -Path C:\MyDeploymentPackages\cms.app.1.0.0.nupkg
The package is now available for usage in a deployment.

To start the code deployment, you can use either code packages or source environment approaches. 

Using code packages

To deploy this package to the Preproduction environment, use the following command:

Start-EpiDeployment -ProjectId 2a561398-d517-4634-9bc4-aab5008a8e1a -DeploymentPackage cms.app.1.0.0.nupkg -TargetEnvironment Preproduction
Using the source environment

To deploy an existing code from a source environment, use the following command: 

Start-EpiDeployment -ProjectId 2a561398-d517-4634-9bc4-aab5008a8e1a -SourceEnvironment Integration -TargetEnvironment Preproduction -SourceApp cms, commerce
  • -SourceApp accepts app type names, CMS and Commerce to specify which app from a source environment to copy

To start a content-only deployment, use the following command:

Start-EpiDeployment -ProjectId 2a561398-d517-4634-9bc4-aab5008a8e1a -SourceEnvironment Integration -TargetEnvironment Preproduction -IncludeBlob -IncludeDb
  • -IncludeBlob switches to copy BLOBs from source to target environment
  • -IncludeDb switched to copy the DB from source to target environment

The deployment starts immediately and the cmdlet returns an object that contains the Id of the deployment. If you want the cmdlet wait until the deployment has finished before it returns anything, add the -Wait switch. (There are also parameters for controlling how long it should wait before timing out.). A -UseMaintenancePage switch uses a maintenance page during the deployment if you have DB changes.

If you want to check the status of deployment or just list deployments made through the API for a project, use the following command:

Get-EpiDeployment -ProjectId 2a561398-d517-4634-9bc4-aab5008a8e1a

To get the details of a specific deployment, specify the Id of that deployment; (it returns the same type of object as Start-EpiDeployment):

PS> Get-EpiDeployment -ProjectId 2a561398-d517-4634-9bc4-aab5008a8e1a -Id 2a52c873-b39c-4f44-b842-aab5009c3060
 
id                 : 2a52c873-b39c-4f44-b842-aab5009c3060
projectId          : 2a561398-d517-4634-9bc4-aab5008a8e1a
status             : InProgress
startTime          : 2019-08-26T09:28:39.479Z
endTime            :
percentComplete    : 2
validationLinks    : {}
deploymentErrors   : {}
deploymentWarnings : {}
parameters         : @{targetEnvironment=Preproduction; packages=System.Object[]; maintenancePage=False}

To see details, expand the parameters property. You can also get the output as JSON:

Get-EpiDeployment -ProjectId 2a561398-d517-4634-9bc4-aab5008a8e1a -Id 2a52c873-b39c-4f44-b842-aab5009c3060 | ConvertTo-Json

After the deployment finishes, choose Reset or Complete using the respective functions such as in the following examples:

Complete

Complete-EpiDeployment -ProjectId 2a561398-d517-4634-9bc4-aab5008a8e1a -Id 2a52c873-b39c-4f44-b842-aab5009c3060

Reset

Reset-EpiDeployment -ProjectId 2a561398-d517-4634-9bc4-aab5008a8e1a -Id 2a52c873-b39c-4f44-b842-aab5009c3060

Reset-EpiDeployment and Complete-EpiDeployment also have a -Wait switch if you want the cmdlets to return after the process has finished.

Most of the cmdlets in the module also support pipelining, such as the following example. (If you do not run the Connect-EpiCloud first, you will need to specify the ClientKey and ClientSecret parameters for both cmdlets also):

Get-EpiDeployment -ProjectId 2a561398-d517-4634-9bc4-aab5008a8e1a -Id 2a52c873-b39c-4f44-b842-aab5009c3060 | Complete-EpiDeployment

Related topics

Last updated: Oct 17, 2019