Deploy using PowerShell
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 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 deployment.
- Get-EpiDeployment – Fetches information about deployments (ongoing or finished).
- Complete-EpiDeployment – Completes a deployment that is in the verification stage. (Same as Complete or Go Live in the management portal)
- Reset-EpiDeployment – Resets or Complete Resets a deployment in the verification or reset-verification stages. (Same as Reset or 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 the status of the database export and return a link to the exported database if it is finished.
For examples of how to use the commands and descriptions on parameters, enter the Get-Help cmdlet in the PowerShell console.
Get-Help Start-EpiDeployment -FullOr, if you want a graphical interface to access the help:
Get-Help Start-EpiDeployment -ShowWindowInstall the module
Get the module from the PowerShell Gallery. To install it, open PowerShell and run the following command:
Install-Module -Name EpiCloud -Scope CurrentUserThis 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 Get 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 EpiCloudAdd 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. For example, you can also specify these for each cmdlet if it is running on a build server.
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 formatCode 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.nupkgThe code package is now available for deployment.
Note If you change the content you have to update the package version. If you attempt to upload a code package with the same name as one already uploaded, the system compares their checksums. If the checksums match, it does not upload the file. However, if the checksums differ, you receive an error because you cannot overwrite an existing package.
Deploy code and content
You can use code packages, source environment, or smooth deploy approaches to start the code deployment.
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 PreproductionDeploy 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 -DirectDeployDeploy 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 Customized 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.
Warning To deploy from a source environment to a target environment, create an API credential through the DXP Management Portal that has permission to both environments.Overwriting content in production is not recommended. However, the deployment API permits copying BLOBs and databases to production if you specified a -SourceApp and a maintenance option (-ZeroDowntime or -MaintenancePage). Be aware that this overwrites ALL content in the production environment. After the initial deployment to production, specifying a -SourceApp is mandatory, and a maintenance option must be chosen for subsequent deployments.
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)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 containing the deployment's Id. 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 list deployments made through the API for the project, use the following command:
Get-EpiDeploymentTo 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-JsonAfter 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-aab5009c3060Reset
Reset-EpiDeployment -Id 2a52c873-b39c-4f44-b842-aab5009c3060If 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 -CompleteReset-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-EpiDeploymentStart-EpiDatabaseExport
Start-EpiDatabaseExport -Environment Integration -DatabaseName epicms -WaitSee also: Optimizely Cloud REST API