Run From Package: a new way to deploy your Azure Web Apps and Function Apps

[davidebbo]

⚠️
Update 9/10/2018: this feature is now GA. You can find the official documentation here: https://docs.microsoft.com/en-us/azure/azure-functions/run-functions-from-deployment-package
⚠️

---

Note: after reading below, please see also this post for additional info.

Also, note that this feature was initially called Run-From-Zip, before being renamed to Run-From-Package.

Quick Start

Run From Package is an exciting new feature which lets you run a Web App or Function App by simply pointing it to a zip file containing your files.

To use it, just add an Azure App Setting called WEBSITE_RUN_FROM_PACKAGE, and point it to your zip (typically using a storage SAS URL), e.g.

WEBSITE_RUN_FROM_PACKAGE=https://davidebbostorage.blob.core.windows.net/content/SampleCoreMVCApp.zip?st=2018-02-13T09%3A48%3A00Z&se=2044-06-14T09%3A48%3A00Z&sp=rl&sv=2017-04-17&sr=b&sig=bNrVrEFzRHQB17GFJ7boEanetyJ9DGwBSV8OM3Mdh%2FM%3D

And that's it! Check out this short video which demonstrates using this.

Note: the easiest way to host your zip is to put it in a Storage Blob. You can use Storage Explorer to do this. And see this doc for details on generating a SAS URL for your blob.

Quick Start (alternative approach without storage account)

There is another approach we're exploring that you can try:

• From Kudu, create a d:\home\data\SitePackages folder, and drop your zip file in there (e.g. site01.zip)
• In the same folder, create a file named packagename.txt, containing the name of your zip file. e.g. it should contain site01.zip and nothing else (important: make sure you have no trailing spaces or newlines after the file name!)
• In your Azure App Settings, set WEBSITE_RUN_FROM_PACKAGE to 1 (same app setting as above, except here it's not set to a url).

Check out this short video which demonstrates this second workflow.

How this is fundamentally different from other deployment techniques

Today, App Service supports a number of different techniques to deploy your files: msdeploy (aka WebDeploy), git, FTP, VSTS, ARM and more. But all these techniques have something in common: when all is said and done, your files are deployed under your wwwroot folder (specifically d:\home\site\wwwroot).

At that point, the runtime takes over, and it is no longer relevant how the files got there. The runtime can read all those files, and run whatever logic it needs to run based on them.

But with Run From Package, things are very different. There is no longer a deployment step which copies the individual files to wwwroot. Instead, you just point it to a zip file, and the zip gets mounted on wwwroot as a read-only file system.

In other word, while all the other techniques are pure deployment-time features, Run From Package is much more of a runtime feature.

What are the benefits of Run From Package?

Atomicity

One big benefit is that deployments become much more atomic. With all the other deployment flows, the App is running off loose files in your wwwroot, and deploying a new version means making changes (additions/deletions/updates) to those existing files, while the site is running. And if you're not careful, you could end up with locked files, and with running a half-baked app.

Of course, there are mitigations you can use today:

• App_Offline.html lets you take your app completely offline so you can update files in peace
• Site Slots let you deploy to a staging slot with no traffic, and swap to Prod when you're ready

But with Run From Package, updating an app becomes as simple as pointing it to a different zip. When you do this, there is never a time where the old files conflict with the new one. Instead, there is an atomic transition between the two. Note that a site restart happens, so this can still be combined with slots if needed.

A side effect of this is that deployments via ARM templates become a lot faster, as all they need to do is update an App Setting.

Predictability

With traditional deployment techniques, it is harder to make sure that you are running the exact file set that you want. The reason is that from one deployment to the next, there are various ways that you can be left with unwanted remnants of the previous deployment. e.g. with msdeploy, you need to deal with whether you want to delete files at the destination, and whether you want to exclude some folders.

Now suppose you have an app that you need to run in multiple regions using traffic manager. You really want each region to be running the exact same files, but it is non-trivial to guarantee this.

In addition, a given running instance could be self-modifying some of its files, leading to discrepancies.

With Run From Package, it is intrinsically a solved problem, because you always know that the only files your site is using are the files in your zip; nothing less and nothing more. If you use the same zip in all regions (or exact copies of it), there is no risk of them diverging.

Faster deployment

At deployment time, there is nothing to extract at all, since everything happens at runtime. For apps with a large number of files, this can make the deployment much faster.

Cold start performance

This one is particularly interesting to Azure Functions users running in Consumption mode, because cold starts are very common as your app is dynamically scaled.

Today, the cold start perf of Azure Functions is not very good when your functions are using Node and have thousands of files in npm modules.

In our tests, using Run From Package in these scenarios lead to a significantly improved cold start. And we are working on further improvements that will make cold start yet faster in the future.

Versioning

As long as you keep previous versions for your zip in your Storage container, you can easily move back to a previous version by just pointing back to it.

By contrast, with other techniques it can be non-trivial to get back to the exact file set that you were at before if something goes wrong.

App 'Subscription' model

With this model, you can have a publisher maintain a zip of their app with a known Storage URL. Consumers can then create apps pointing to that zip, and know that they'll always be running the latest (caveat: it takes an app restart to re bind to the latest).

What are the limitations of Run From Package?

Your site files become read-only

This actually should be viewed as a good thing. Generally, best practice dictates that you should avoid writing any files to your wwwroot folder at runtime. Instead, you should be using external mechanism like Azure Storage or a SQL database to persist any state.

With Run From Package, this is strictly enforced as the wwwroot folder becomes read-only. You can still write files to the %TMP% folder if you need temporary storage. But you cannot save files to places like App_Data (but really, you shouldn't be doing that!)

There is limited tooling support today

You can always use it 'manually' by creating the zip, hosting it, and pointing the App Setting to it.

There is also tooling support in VS and VSTS to automatically enable it on publishing, but currently it is only for Function Apps. Web App support will come later.

Windows only

This feature is currently Windows only, so it is not yet supported in App Service for Linux.

Issue with Zip containing files that use Unicode characters in their name

It has been reported that if some file names use Unicode characters, the names become corrupted when the zip is mounted as a file system. We are investigating this further.

Q&A

What will my wwwroot folder look like in Kudu Console

With Run From Package, if you go into your d:\home\site\wwwroot folder from Kudu Console, you will see all the files from your zip, but the whole folder will be read-only. This is the same view that your runtime will have.

What about other folders under d:\home

Run From Package only affects your wwwroot folder, so the rest will continue unaffected. e.g. log files can still get created under d:\home\LogFiles.

How does that affect WebJobs?

There are really two scenario for WebJobs:

1. those that are deployed with your Web App
2. those that are deployed separately from your Web App

The first kind if simple, as they will just be part of the zip file, along with the rest of the app. But for those that are deployed separately (e.g. App Insights deploys a WebJob), things are trickier because they can't just be uploaded to d:\home\site\wwwroot\app_data\jobs\..., which is read-only.

To solve this, WebJobs can now also be deployed to d:\home\site\jobs\.... Jobs from both locations can exist in the same app.

Tar-gzip support?

No, only support the normal zip format.

Does this work with local cache feature?

No, the feature does not compose with local cache. In fact, it could lead to failure and enabling both.

[davidebbo]

To give as feedback on this feature, please go to Azure/app-service-announcements-discussions#32. Thanks!

[davidebbo]

Note that we are renaming this feature from Run-From-Zip to Run From Package (already renamed in the announcement above). While only the zip format is supported today, the rename opens the door for supporting additional formats in the future.

Right now, the App Setting is still WEBSITE_RUN_FROM_ZIP, and we will continue to support this key indefinitely. For consistency with the feature name, we will also add support for WEBSITE_RUN_FROM_PACKAGE in a couple weeks.