Deploying a package to an Azure Web App

Last updated

Octopus Deploy supports automated deployment of Azure Web Apps (formerly known as Azure Web Sites).

Understanding Azure Web Apps

The Azure Web Apps you build, and how you might want to deploy them, are becoming increasingly complex as the Azure team provide more features to the platform. The best place to stay abreast of changes, and how they might affect your deployments is the Azure Web App Documentation, the many and varied ways you can deploy Web Apps (including Octopus Deploy). There is also the hidden gem of the Project Kudu GitHub repository where you will find many of the hard to find facts about Web Jobs (like the settings.job file, configuring a Continuous Web Job as a Singleton, configuring the Schedule for Scheduled Jobs, how shadow copying enables in-place deployments, and how to shut down gracefully).

Web Apps are deployed using Web Deploy

Deploying an Azure Web App with Octopus Deploy behaves very similarly to the Visual Studio publish wizard and uses Web Deploy to synchronize the files in your package to the Azure Web App. Similarly to Visual Studio you can change how Octopus Deploy invokes Web Deploy using the following options in your deployment steps which enable the most common deployment scenarios. All of these options are discussed below where we describe how to configure the Azure Web App step.

Defaults match Visual Studio
The default values for these variables were chosen to match Visual Studio following the principle of least surprise. You will typically need to adjust these values depending on your specific circumstances.

Web Jobs

You can build Web Jobs in almost any way you can imagine, so let's focus this discussion on deploying Web Jobs. Web Jobs are deployed by simply copying the files into the right place in the Web App file system.

When you use Octopus Deploy to deploy a package to an Azure Web App it will synchronize the files from your package into the Web App via Web Deploy where the root folder of the package matches the root folder of the Web App.

To deploy a Web Job with Octopus Deploy you simply need to add the executable Web Job(s) into the appropriate folder(s) of your package and deploy them to the Web App.

  • Triggered Web Jobs should be added to the app_data/jobs/triggered/{job_name} folder
  • Continuous Web Jobs should be added to the app_data/jobs/continuous/{job_name} folder

See below for more information on packaging Azure Web Apps including Web Jobs.

For more information refer to the Project Kudu documentation on Web Jobs.

Step 1: Packaging

Your application should be packaged into a supported package where the contents of the package will be synchronized with the Azure Web App via Web Deploy. Your package should include any content and binaries for your Web Site and any Web Jobs using the same folder structure that is expected by the Azure Web App hosting environment.

Example Azure Web App package with Web Jobs

                    |   WebJob1.exe
                    |   WebJob1.exe.config
                    |   WebJob2.exe
                    |   WebJob2.exe.config

A really convenient way to package Web Apps is using OctoPack. Here's a simplified example that would build the package discussed above.


<?xml version="1.0"?>
<package >
    <description>MyWebApp with WebJobs</description>
    <copyright>Copyright 2015 MyCompany</copyright>
  	<file src="..\WebJob1\bin\**\*.*" target="app_data\jobs\continuous\WebJob1" />
  	<file src="..\WebJob2\bin\**\*.*" target="app_data\jobs\triggered\WebJob2" />

If the  section exists, OctoPack by default won't attempt to automatically add any extra files to your package, so you'll need to be explicit about which files you want to include. You can override this behavior with /p:OctoPackEnforceAddingFiles=true

Here's an example project file with some of the OctoPack configuration set as properties that are convenient for WebApps and WebJobs.


  <RunOctoPack>true</RunOctoPack><!-- Run OctoPack on every build which is really convenient for testing your package process works as expected -->
  <OctoPackEnforceAddingFiles>true</OctoPackEnforceAddingFiles><!-- Package files included by convention because it's a web project, and package files specified by the <files> node of the nuspec -->
  <OctoPackPublishPackageToFileShare>..\..\artifacts</OctoPackPublishPackageToFileShare><!-- Publish the resultant package to the ..\..\artifacts folder -->

Simple and advanced deployment scenarios

The example we've discussed here is the most common scenario for deploying Azure Web Apps: a single package that contains an ASP.NET Web Application and some Web Jobs in the same release cadence. It is possible to implement more complex deployment scenarios where the ASP.NET Web Application and each Web Job follow independent release cadences. In this case you would build multiple packages using the folder structure expected by the Azure Web App hosting framework discussed earlier. Once you've done that you can simply reuse the same Azure Web App Deployment Target to deploy each package when they are released.

Deploy only files that have changed

NuGet packages are extracted locally and the timestamps are updated at that point in time. It will deploy every file regardless if it has changed or not. If you want to deploy only the changed files, consider these options:

  • Use the Checksum file comparison method to only deploy files that have changed. This may work well for moderately-sized applications, but may be prohibitively slow and unreliable for large applications.
  • Use Zip packages instead of NuGet. Timestamps are preserved in Zip packages end-to-end throughout the deployment process.

We have written about these options in detail in our blog.

Step 2: Create an Azure Account

If you haven't already, create an Azure Account to grant Octopus Deploy access to your Azure Subscription.

Step 3: Create the Azure Web App deployment step

  1. Add a new 'Deploy an Azure Web App' step to your project. For information about adding a step to the deployment process, see the add step section. 

Step 4: Configure your Azure Web App step.

Once an Account is selected, the list of Azure Web Apps available to the subscription associated with the account will populate the 'Web App' select-list.

If you choose to run this step on behalf of target roles (maybe you are deploying to multiple geographic regions), you will need to ensure a Deployment Target exists when deploying your Azure Web App. For this, we introduced Cloud Regions. If you select a role and no Deployment Targets exist at the time of deploying, Octopus will log warnings in your deployment's task log.

Setting Default Description
Account The Azure Account you want to target when deploying this web app. Select one from the list, or use a variable binding to select an account by its name or ID.
Web App The actual web app you want to target. Select one from the list, or use a variable binding to define the name of the web app.
Physical Path The physical path relative to site root on the web app host. e.g. 'foo' will deploy to 'site\wwwroot\foo'. Leave blank to deploy to root.
Remove additional files False When True instructs Web Deploy to delete files from the destination that aren't in the source package
Preserve App_Data False When True instructs Web Deploy to skip Delete operations in the App_Data directory
Enable AppOffline False When True instructs Web Deploy to place app_offline.htm in root deployment directory to safely bring down the app domain.
Click here for more details.
File comparison method Timestamp Can be timestamp or checksum and instructs web deploy to use the selected algorithm to determine which files to update.
Note: There have been some issues with checksum in earlier versions of web deploy, and we've written about that in detail here.

Use variable binding expressions
Any of the settings above can be switched to use a variable binding expression. A common example is when you use a naming convention for your different web apps, like MyApp_Production and MyApp_Test - you can use environment-scoped variables to automatically configure this step depending on the environment you are targeting.

Deployment features available to Azure Web App steps

The following features are available when deploying a package to an Azure Web App.

Please note these features actually run on the Octopus Server prior to executing web deploy to synchronize the resultant files to the Azure Web App slot. They don't execute in the Azure Web App host you are eventually targeting.

For your convenience the PowerShell session for your custom scripts will have the Azure PowerShell module loaded, and the subscription from the account associated with the target will be selected. This means you don't have to worry about loading the Azure PowerShell module nor authenticate with Azure yourself. See the Azure Powershell documentation for more information. You can write very straightforward scripts like the example below which is from our guide on using deployment slots with Azure Web Apps:

#Swap the staging slot into production
Switch-AzureWebsiteSlot -Name #{WebSite} -Slot1 Staging -Slot2 Production -Force

Deployment process

Deployment to an Azure Web App proceeds as follows (more details provided below):

  1. Download the package from the package repository
  2. Extract the package on the Octopus server to a temporary location
  3. Any configured or packaged PreDeploy scripts are executed
  4. Substitute variables in files (if configured)
  5. XML configuration transformations (if configured) are performed
  6. XML configuration variables (if configured) are replaced
  7. Any configured or package Deploy scripts are executed
  8. Execute web deploy to synchronize the resultant files in the temporary location to the web app host
  9. Any configured or packaged PostDeploy scripts are executed

Deploying to multiple geographic regions

When your application is deployed to more than one geographic region, you are likely to need per-region configuration settings. You can achieve this result in many different ways, but the two most popular methods we have seen are:

  1. Cloud Regions: introduced in Octopus 3.4 to enable rolling deployments across multiple geographic regions
  2. Environment-per-region: by creating an environment per region you can leverage lifecycles to create a strict release promotion process

Both methods allow you to modify your deployment process and variables per-region, but have slightly different release promotion paths. Choose the one that suits you best.

In This Section

The following topics are explained further in this section: