Merge pull request #101070 from cephalin/runpackage

add run-from-package to app service docs

Author: v-albemi

articles/app-service/containers/toc.yml

@@ -103,6 +103,8 @@
     items:
     - name: Deploy the app
       items:
+      - name: Run from package
+        href: ../deploy-run-package.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json
       - name: Deploy via FTP
         href: ../deploy-ftp.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json
       - name: Deploy via cloud sync

articles/app-service/deploy-run-package.md

@@ -0,0 +1,72 @@
+---
+title: Run your app from a ZIP package 
+description: Deploy your app's ZIP package with atomicity. Improve the predictability and reliability of your app's behavior during the ZIP deployment process.
+ms.topic: article
+ms.date: 01/14/2020
+
+---
+
+# Run your app in Azure App Service directly from a ZIP package
+
+In [Azure App Service](overview.md), you can run your apps directly from a deployment ZIP package file. This article shows how to enable this functionality in your app.
+
+All other deployment methods in App Service have something in common: your files are deployed to *D:\home\site\wwwroot* in your app (or */home/site/wwwroot* for Linux apps). Since the same directory is used by your app at runtime, it's possible for deployment to fail because of file lock conflicts, and for the app to behave unpredictably because some of the files are not yet updated.
+
+In contrast, when you run directly from a package, the files in the package are not copied to the *wwwroot* directory. Instead, the ZIP package itself gets mounted directly as the read-only *wwwroot* directory. There are several benefits to running directly from a package:
+
+- Eliminates file lock conflicts between deployment and runtime.
+- Ensures only full-deployed apps are running at any time.
+- Can be deployed to a production app (with restart).
+- Improves the performance of Azure Resource Manager deployments.
+- May reduce cold-start times, particularly for JavaScript functions with large npm package trees.
+
+> [!NOTE]
+> Currently, only ZIP package files are supported.
+
+[!INCLUDE [Create a project ZIP file](../../includes/app-service-web-deploy-zip-prepare.md)]
+
+## Enable running from package
+
+The `WEBSITE_RUN_FROM_PACKAGE` app setting enables running from a package. To set it, run the following command with Azure CLI.
+
+```azurecli-interactive
+az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings WEBSITE_RUN_FROM_PACKAGE="1"
+```
+
+`WEBSITE_RUN_FROM_PACKAGE="1"` lets you run your app from a package local to your app. You can also [run from a remote package](#run-from-external-url-instead).
+
+## Run the package
+
+The easiest way to run a package in your App Service is with the Azure CLI [az webapp deployment source config-zip](/cli/azure/webapp/deployment/source?view=azure-cli-latest#az-webapp-deployment-source-config-zip) command. For example:
+
+```azurecli-interactive
+az webapp deployment source config-zip --resource-group <group-name> --name <app-name> --src <filename>.zip
+```
+
+Because the `WEBSITE_RUN_FROM_PACKAGE` app setting is set, this command doesn't extract the package content to the *D:\home\site\wwwroot* directory of your app. Instead, it uploads the ZIP file as-is to *D:\home\data\SitePackages*, and creates a *packagename.txt* in the same directory, that contains the name of the ZIP package to load at runtime. If you upload your ZIP package in a different way (such as [FTP](deploy-ftp.md)), you need to create the *D:\home\data\SitePackages* directory and the *packagename.txt* file manually.
+
+The command also restarts the app. Because `WEBSITE_RUN_FROM_PACKAGE` is set, App Service mounts the uploaded package as the read-only *wwwroot* directory and runs the app directly from that mounted directory.
+
+## Run from external URL instead
+
+You can also run a package from an external URL, such as Azure Blob Storage. You can use the [Azure Storage Explorer](../vs-azure-tools-storage-manage-with-storage-explorer.md) to upload package files to your Blob storage account. You should use a private storage container with a [Shared Access Signature (SAS)](../vs-azure-tools-storage-manage-with-storage-explorer.md#generate-a-sas-in-storage-explorer) to enable the App Service runtime to access the package securely. 
+
+Once you upload your file to Blob storage and have an SAS URL for the file, set the `WEBSITE_RUN_FROM_PACKAGE` app setting to the URL. The following example does it by using Azure CLI:
+
+```azurecli-interactive
+az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_RUN_FROM_PACKAGE="https://myblobstorage.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"
+```
+
+If you publish an updated package with the same name to Blob storage, you need to restart your app so that the updated package is loaded into App Service.
+
+## Troubleshooting
+
+- Running directly from a package makes `wwwroot` read-only. Your app will receive an error if it tries to write files to this directory.
+- TAR and GZIP formats are not supported.
+- This feature is not compatible with [local cache](overview-local-cache.md).
+- For improved cold-start performance, use the local Zip option (`WEBSITE_RUN_FROM_PACKAGE`=1).
+
+## More resources
+
+- [Continuous deployment for Azure App Service](deploy-continuous-deployment.md)
+- [Deploy code with a ZIP or WAR file](deploy-zip.md)

articles/app-service/deploy-zip.md

@@ -16,74 +16,50 @@ This ZIP file deployment uses the same Kudu service that powers continuous integ
 
 - Deletion of files left over from a previous deployment.
 - Option to turn on the default build process, which includes package restore.
-- [Deployment customization](https://github.com/projectkudu/kudu/wiki/Configurable-settings#repository-and-deployment-related-settings), including running deployment scripts.  
+- Deployment customization, including running deployment scripts.  
 - Deployment logs. 
 - A file size limit of 2048 MB.
 
 For more information, see [Kudu documentation](https://github.com/projectkudu/kudu/wiki/Deploying-from-a-zip-file).
 
 The WAR file deployment deploys your [WAR](https://wikipedia.org/wiki/WAR_(file_format)) file to App Service to run your Java web app. See [Deploy WAR file](#deploy-war-file).
 
-[!INCLUDE [quickstarts-free-trial-note](../../includes/quickstarts-free-trial-note.md)]
-
 ## Prerequisites
 
-To complete the steps in this article:
-
-* [Create an App Service app](/azure/app-service/), or use an app that you created for another tutorial.
-
-## Create a project ZIP file
-
->[!NOTE]
-> If you downloaded the files in a ZIP file, extract the files first. For example, if you downloaded a ZIP file from GitHub, you cannot deploy that file as-is. GitHub adds additional nested directories, which do not work with App Service. 
->
-
-In a local terminal window, navigate to the root directory of your app project. 
-
-This directory should contain the entry file to your web app, such as _index.html_, _index.php_, and _app.js_. It can also contain package management files like _project.json_, _composer.json_, _package.json_, _bower.json_, and _requirements.txt_.
+To complete the steps in this article, [create an App Service app](/azure/app-service/), or use an app that you created for another tutorial.
 
-Create a ZIP archive of everything in your project. The following command uses the default tool in your terminal:
-
-```
-# Bash
-zip -r <file-name>.zip .
+[!INCLUDE [quickstarts-free-trial-note](../../includes/quickstarts-free-trial-note.md)]
 
-# PowerShell
-Compress-Archive -Path * -DestinationPath <file-name>.zip
-``` 
+[!INCLUDE [Create a project ZIP file](../../includes/app-service-web-deploy-zip-prepare.md)]
 
 [!INCLUDE [Deploy ZIP file](../../includes/app-service-web-deploy-zip.md)]
 The above endpoint does not work for Linux App Services at this time. Consider using FTP or the [ZIP deploy API](https://docs.microsoft.com/azure/app-service/containers/app-service-linux-faq#continuous-integration-and-deployment) instead.
 
 ## Deploy ZIP file with Azure CLI
 
-Make sure your Azure CLI version is 2.0.21 or later. To see which version you have, run `az --version` command in your terminal window.
-
 Deploy the uploaded ZIP file to your web app by using the [az webapp deployment source config-zip](/cli/azure/webapp/deployment/source?view=azure-cli-latest#az-webapp-deployment-source-config-zip) command.  
 
 The following example deploys the ZIP file you uploaded. When using a local installation of Azure CLI, specify the path to your local ZIP file for `--src`.
 
 ```azurecli-interactive
-az webapp deployment source config-zip --resource-group myResourceGroup --name <app_name> --src clouddrive/<filename>.zip
+az webapp deployment source config-zip --resource-group <group-name> --name <app-name> --src clouddrive/<filename>.zip
 ```
 
 This command deploys the files and directories from the ZIP file to your default App Service application folder (`\home\site\wwwroot`) and restarts the app.
 
 By default, the deployment engine assumes that a ZIP file is ready to run as-is and doesn't run any build automation. To enable the same build automation as in a [Git deployment](deploy-local-git.md), set the `SCM_DO_BUILD_DURING_DEPLOYMENT` app setting by running the following command in the [Cloud Shell](https://shell.azure.com):
 
 ```azurecli-interactive
-az webapp config appsettings set --resource-group <resource-group-name> --name <app-name> --settings SCM_DO_BUILD_DURING_DEPLOYMENT=true
+az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings SCM_DO_BUILD_DURING_DEPLOYMENT=true
 ```
 
-
-
 For more information, see [Kudu documentation](https://github.com/projectkudu/kudu/wiki/Deploying-from-a-zip-file-or-url).
 
 [!INCLUDE [app-service-deploy-zip-push-rest](../../includes/app-service-deploy-zip-push-rest.md)]  
 
 ## Deploy WAR file
 
-To deploy a WAR file to App Service, send a POST request to `https://<app_name>.scm.azurewebsites.net/api/wardeploy`. The POST request must contain the .war file in the message body. The deployment credentials for your app are provided in the request by using HTTP BASIC authentication.
+To deploy a WAR file to App Service, send a POST request to `https://<app-name>.scm.azurewebsites.net/api/wardeploy`. The POST request must contain the .war file in the message body. The deployment credentials for your app are provided in the request by using HTTP BASIC authentication.
 
 Always use `/api/wardeploy` when deploying WAR files. This API will expand your WAR file and place it on the shared file drive. using other deployment APIs may result in inconsistent behavior. 
 
@@ -94,7 +70,7 @@ For the HTTP BASIC authentication, you need your App Service deployment credenti
 The following example uses the cURL tool to deploy a .war file. Replace the placeholders `<username>`, `<war-file-path>`, and `<app-name>`. When prompted by cURL, type in the password.
 
 ```bash
-curl -X POST -u <username> --data-binary @"<war-file-path>" https://<app_name>.scm.azurewebsites.net/api/wardeploy
+curl -X POST -u <username> --data-binary @"<war-file-path>" https://<app-name>.scm.azurewebsites.net/api/wardeploy
 ```
 
 ### With PowerShell

articles/app-service/toc.yml

@@ -117,6 +117,8 @@
     items:
     - name: Deploy the app
       items:
+      - name: Run from package
+        href: deploy-run-package.md
       - name: Deploy ZIP or WAR
         href: deploy-zip.md
       - name: Deploy via FTP

includes/app-service-deploy-atomicity.md

@@ -14,6 +14,6 @@ ms.custom: "include file"
 
 All the officially supported deployment methods make changes to the files in the `/home/site/wwwroot` folder of your app. These files are used to run your app. Therefore, the deployment can fail because of locked files. The app may also behave unpredictably during deployment, because not all the files updated at the same time. This is undesirable for a customer-facing app. There are a few different ways to avoid these issues:
 
+- [Run your app from the ZIP package directly](../articles/app-service/deploy-run-package.md) without unpacking it.
 - Stop your app or enable offline mode for your app during deployment. For more information, see [Deal with locked files during deployment](https://github.com/projectkudu/kudu/wiki/Dealing-with-locked-files-during-deployment).
 - Deploy to a [staging slot](../articles/app-service/deploy-staging-slots.md) with [auto swap](../articles/app-service/deploy-staging-slots.md#configure-auto-swap) enabled. 
-- Use [Run From Package](https://github.com/Azure/app-service-announcements/issues/84) instead of continuous deployment.

includes/app-service-web-deploy-zip-prepare.md

@@ -0,0 +1,34 @@
+---
+title: "include file"
+description: "include file"
+services: app-service
+author: cephalin
+ms.service: app-service
+ms.topic: "include"
+ms.date: 01/14/2020
+ms.author: cephalin
+ms.custom: "include file"
+---
+
+## Create a project ZIP file
+
+>[!NOTE]
+> If you downloaded the files in a ZIP file, extract the files first. For example, if you downloaded a ZIP file from GitHub, you cannot deploy that file as-is. GitHub adds additional nested directories, which do not work with App Service. 
+>
+
+In a local terminal window, navigate to the root directory of your app project. 
+
+This directory should contain the entry file to your web app, such as _index.html_, _index.php_, and _app.js_. It can also contain package management files like _project.json_, _composer.json_, _package.json_, _bower.json_, and _requirements.txt_.
+
+Unless you want App Service to run deployment automation for you, run all the build tasks (for example, `npm`, `bower`, `gulp`, `composer`, and `pip`) and make sure that you have all the files you need to run the app. This step is required if you want to [run your package directly](../articles/app-service/deploy-run-package.md).
+
+Create a ZIP archive of everything in your project. The following command uses the default tool in your terminal:
+
+```
+# Bash
+zip -r <file-name>.zip .
+
+# PowerShell
+Compress-Archive -Path * -DestinationPath <file-name>.zip
+``` 
+