Deploy using PowerShell
Describes how to deploy using the Deployment API for Optimizely Digital Experience Platform (DXP), 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 – Supplies the required credentials to other commands in the module, simplifying overall cmdlet usage.
-
Get-EpiDeploymentPackageLocation – Returns a SAS link to upload deployment packages to using Add-EpiDeploymentPackage.
-
Add-EpiDeploymentPackage – Upload a deployment package to the DXP environment to use for deployments; requires the Azure PowerShell modules (Azure.Storage or Az.Storage) to run.
-
Start-EpiDeployment – Starts a new deployment.
-
Get-EpiDeployment – Fetches information about deployments (ongoing or finished).
-
Complete-EpiDeployment – Completes a deployment that is in the verification stage. (Same as Complete/Go Live in the management portal)
-
Reset-EpiDeployment – Resets or Complete Reset a deployment that is in the verification stage or reset-verification stage. (Same as Reset/Complete Reset in the management portal.)
Note
You can restore the database if you used UseMaintenancePage parameter for the deployment.
-
Start-EpiDatabaseExport – Starts a database export. You can specify the wait parameter to wait until the export has finished.
-
Get-EpiDatabaseExport – Get status of database export, and returns a link to the exported database if it has finished.
For examples about how to use the commands and descriptions on parameters, enter the Get-Help cmdlet in the PowerShell console.
Get-Help Start-EpiDeployment -Full
Or if you want a graphical interface to access the help:
Get-Help Start-EpiDeployment -ShowWindow
Install the module
Get the module from 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 Getting Started with the PowerShell Gallery by Microsoft.
Import the module
If you install the module from the PowerShell Gallery, the module is automatically loaded when you call a cmdlet. To explicitly import the module, use the following command:
Import-Module EpiCloud
Add credentials to the PowerShell scope
Optionally, you can add your credentials to the current PowerShell scope by calling the Connect-EpiCloud cmdlet with your ClientKey, ClientSecret, and ProjectId, after which you do not have to specify the ClientKey, ClientSecret, or ProjectId for any other of the cmdlets in the module during the session. You also can specify these for each cmdlet if running on a build server for example.
Connect-EpiCloud -ClientKey <ClientKey> -ClientSecret <ClientSecret> -ProjectId <ProjectId>
Upload a code package to DXP
To upload a code package to your DXP project, run Get-EpiDeploymentPackageLocation to get the SAS link where the package should be uploaded, and then Add-EpiDeploymentPackage to upload that package, as follows. See Code package format for details on what the package should look like.
$saslink = Get-EpiDeploymentPackageLocation
Add-EpiDeploymentPackage -SasUrl $saslink -Path C:\MyDeploymentPackages\cms.app.1.0.0.nupkg
The code package is now available for deployment.
Deploy code and content
To start the code deployment, you can use code packages, source environment, or smooth deploy approaches.
Deploy from the code package
To deploy this package to the Preproduction environment, use the following command:
Start-EpiDeployment -DeploymentPackage cms.app.1.0.0.nupkg -TargetEnvironment Preproduction
Deploy directly to Web App without a slot swap
To speed up deployments, use DirectDeploy to deploy directly to the target Web App without performing a swap. You can apply DirectDeploy for Integration, Development, and Testing target environments:
Start-EpiDeployment -DeploymentPackage cms.app.1.0.0.nupkg -TargetEnvironment Integration -DirectDeploy
Deploy from a source environment
To deploy code from a source environment, use the following command:
Start-EpiDeployment -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 deploy content, use the following command:Start-EpiDeployment -SourceEnvironment Integration -TargetEnvironment Preproduction -IncludeBlob -IncludeDb
-
-IncludeBlob copies BLOBs from source to target environment.
-
-IncludeDb copies the DB from source to target environment.
Deploy with smooth deployment
You can use Smooth deploy/Zero Downtime deployment (ZDD) for code packages and a source environment. See Smooth deployment (Zero Downtime Deployments) and use the following command:
Start-EpiDeployment -SourceEnvironment Integration -TargetEnvironment Preproduction -ZeroDowntimeMode ReadOnly
- -ZeroDowntimeMode accepts values ReadOnly and ReadWrite. For sites that do not support ZDD (such as Commerce Manager), a maintenance page is used instead (if those sites are part of the deployment).
Start the deployment
The deployment starts immediately and the cmdlet returns an object that contains the Id of the deployment. If you specify the -Wait switch the cmdlet waits for the deployment to finish before it returns. You can use the -UseMaintenancePage switch to enable a maintenance page during the deployment if there are DB changes.
Use -Verbose for additional logging information. (This switch can be added to any cmdlet.)
If you want to check the status of deployment or just list deployments made through the API for the project, use the following command:
Get-EpiDeployment
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 -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 -Id 2a52c873-b39c-4f44-b842-aab5009c3060 | ConvertTo-Json
After the deployment finishes, run Reset or Complete using the respective functions such as in the following examples:
Complete
Complete-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060
Reset
Reset-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060
If UseMaintenancePage parameter was used for the deployment, you can use RollbackDatabase and ValidateBeforeSwap options when you reset a deployment. Use ValidateBeforeSwap option to validate the reset progress before completing reset._
Complete Reset
Reset-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060 -Complete
Reset-EpiDeployment and Complete-EpiDeployment also have a -Wait switch if you want the cmdlets to return after the action has finished.
Most of the cmdlets in the module also support pipelining, such as the following example:
Get-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060 | Complete-EpiDeployment
Start-EpiDatabaseExport
Start-EpiDatabaseExport -Environment Integration -DatabaseName epicms -Wait
See also: Optimizely Cloud REST API
Updated 3 days ago