Deploy files to Azure App Service

Article
2025-03-31

Note

Starting June 1, 2024, newly created App Service apps can generate a unique default host name that uses the naming convention <app-name>-<random-hash>.<region>.azurewebsites.net. For example: myapp-ds27dh7271aah175.westus-01.azurewebsites.net. Existing app names remain unchanged.

For more information, see the blog post about creating a web app with a unique default host name.

This article shows you how to deploy your code as a ZIP, WAR, JAR, or EAR package to Azure App Service. It also shows you how to deploy individual files to App Service, separate from your application package.

Prerequisites

To complete the steps in this article, create an App Service app, or use an app that you created for another tutorial.

If you don't have an Azure subscription, create an Azure free account before you begin.

Create a project ZIP package

Important

When you create the ZIP package for deployment, don't include the root directory. Include only the files and directories in the root directory. If you download a GitHub repository as a ZIP file, you can't deploy that file as-is to App Service. GitHub adds nested directories at the top level, which doesn't 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.

If you don't want App Service to run deployment automation for you, run all the build tasks. For example: npm, bower, gulp, composer, and pip. 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.

Create a ZIP archive of everything in your project. For dotnet projects, add everything in the output directory of the dotnet publish command, excluding the output directory itself. For example, enter the following command in your terminal to create a ZIP package that includes the contents of the current directory:

# Bash
zip -r <file-name>.zip .

# PowerShell
Compress-Archive -Path * -DestinationPath <file-name>.zip

Deploy a ZIP package

When you deploy a ZIP package, App Service unpacks its contents in the default path for your app: D:\home\site\wwwroot for Windows and /home/site/wwwroot for Linux.

This ZIP package deployment uses the same Kudu service that powers continuous integration-based deployments. Kudu supports the following functionality for ZIP package deployment:

Deletion of files left over from a previous deployment
Option to turn on the default build process, which includes package restore
Deployment customization, including running deployment scripts
Deployment logs
A package size limit of 2,048 megabytes

Note

Files in the ZIP package are copied only if their timestamps don't match what is already deployed.

Deploy with ZIP deploy UI in Kudu

In the browser, go to https://<app_name>.scm.azurewebsites.net/ZipDeployUI. For the app name, see the note at the beginning of the article.

Upload the ZIP package you created in Create a project ZIP package. Drag it to the File Explorer area on the web page.

When deployment is in progress, an icon in the top right corner shows you the progress percentage. The page also displays messages for the operation below the File Explorer area. When deployment finishes, the last message should say "Deployment successful."

This endpoint doesn't work for App Service on Linux at this time. Consider using FTP or the ZIP deploy API instead.

Deploy without ZIP deploy UI in Kudu

Deploy a ZIP package to your web app by using the az webapp deploy command. The CLI command uses the Kudu publish API to deploy the files and can be fully customized.

The following example pushes a ZIP package to your site. Specify the path to your local ZIP package for --src-path.

az webapp deploy --resource-group <group-name> --name <app-name> --src-path <zip-package-path>

This command restarts the app after deploying the ZIP package.

The following example uses Publish-AzWebapp to upload the ZIP package. Replace the placeholders <group-name>, <app-name>, and <zip-package-path>.

Publish-AzWebApp -ResourceGroupName Default-Web-WestUS -Name MyApp -ArchivePath <zip-package-path>

The following example uses the client URL (cURL) tool to deploy a ZIP package. Replace the placeholders <zip-package-path> and <app-name>. If you choose basic authentication, supply the deployment credentials in <username> and <password>.

# Microsoft Entra authentication
TOKEN=$(az account get-access-token --query accessToken | tr -d '"')

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -T @"<zip-package-path>" \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=zip"

# Basic authentication
curl -X POST \
     -u '<username>:<password>' \
     -T "<zip-package-path>" \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=zip"

Note

Get the actual fully qualified domain name to use in the URL from the note at the beginning of the article.

Enable build automation for ZIP deploy

By default, the deployment engine assumes that a ZIP package is ready to run as-is and doesn't run any build automation. To enable the same build automation used in a Git deployment, set the SCM_DO_BUILD_DURING_DEPLOYMENT app setting. Run the following command in Azure Cloud Shell:

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.

Deploy WAR, JAR, or EAR packages

You can deploy your WAR, JAR, or EAR package to App Service to run your Java web app by using the Azure CLI, PowerShell, or Kudu publish API.

The deployment process shown here puts the package on the app's content share with the right naming convention and directory structure. For more information, see Kudu publish API reference. We recommend this approach. If you deploy WAR, JAR, or EAR packages by using FTP or Web Deploy instead, you might see unknown failures due to mistakes in the naming or structure.

Deploy a WAR package to Tomcat or JBoss EAP by using the az webapp deploy command. Specify the path to your local Java package for --src-path.

az webapp deploy --resource-group <group-name> --name <app-name> --src-path ./<package-name>.war

The CLI command uses the Kudu publish API to deploy the package and can be fully customized.

The following example uses Publish-AzWebapp to upload the WAR file. Replace the placeholders <group-name>, <app-name>, and <package-path>. Azure PowerShell supports only WAR and JAR files.

Publish-AzWebapp -ResourceGroupName <group-name> -Name <app-name> -ArchivePath <package-path>

The following example uses the cURL tool to deploy a WAR, JAR, or EAR file. Replace the placeholders <file-path>, <app-name>, and <package-type> (war, jar, or ear). If you choose basic authentication, supply the deployment credentials in <username> and <password>.

# Microsoft Entra authentication
TOKEN=$(az account get-access-token --query accessToken | tr -d '"')

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -T @"<file-path>" \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=<package-type>"

# Basic authentication
curl -X POST \
     -u <username>:<password> \
     -T @"<file-path>" \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=<package-type>"

Note

Get the actual fully qualified domain name to use in the URL from the note at the beginning of the article.

For more information, see Kudu publish API reference.

Deploy individual files

Deploy a startup script, library, and static file to your web app by using the az webapp deploy command with the --type parameter.

If you deploy a startup script this way, App Service automatically uses your script to start your app.

The CLI command uses the Kudu publish API to deploy the files. The command can be fully customized.

Deploy a startup script

az webapp deploy --resource-group <group-name> --name <app-name> --src-path scripts/startup.sh --type=startup

Deploy a library file

az webapp deploy --resource-group <group-name> --name <app-name> --src-path driver.jar --type=lib

Deploy a static file

az webapp deploy --resource-group <group-name> --name <app-name> --src-path config.json --type=static

Deploy a startup script

The following example uses the cURL tool to deploy a startup file for the application. Replace the placeholders <startup-file-path> and <app-name>. If you choose basic authentication, supply the deployment credentials in <username> and <password>.

# Microsoft Entra authentication
TOKEN=$(az account get-access-token --query accessToken | tr -d '"')

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -T @"<startup-file-path>" \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=startup"

# Basic authentication
curl -X POST \
     -u <username>:<password> \
     -T @"<startup-file-path>" \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=startup"

Note

Get the actual fully qualified domain name to use in the URL from the note at the beginning of the article.

Deploy a library file

The following example uses the cURL tool to deploy a library file for the application. Replace the placeholders <lib-file-path> and <app-name>. If you choose basic authentication, supply the deployment credentials in <username> and <password>.

# Microsoft Entra authentication
TOKEN=$(az account get-access-token --query accessToken | tr -d '"')

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -T @"<lib-file-path>" \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=lib&path=/home/site/deployments/tools/my-lib.jar"

# Basic authentication
curl -X POST \
     -u <username>:<password> \
     -T @"<lib-file-path>" \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=lib&path=/home/site/deployments/tools/my-lib.jar"

Note

Get the actual fully qualified domain name to use in the URL from the note at the beginning of the article.

Deploy a static file

The following example uses the cURL tool to deploy a config file for the application. Replace the placeholders <config-file-path> and <app-name>. If you choose basic authentication, supply the deployment credentials in <username> and <password>.

# Microsoft Entra authentication
TOKEN=$(az account get-access-token --query accessToken | tr -d '"')

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -T @"<config-file-path>" \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=static&path=/home/site/deployments/tools/my-config.json"

# Basic authentication
curl -X POST \
     -u <username>:<password> \
     -T @"<config-file-path>" \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=static&path=/home/site/deployments/tools/my-config.json"

Note

Get the actual fully qualified domain name to use in the URL from the note at the beginning of the article.

Deploy to network-secured apps

Depending on your web app's networking configuration, direct access to the app from your development environment might be blocked. (See Deploying to network-secured sites and Deploying to network-secured sites, part 2.) Instead of pushing the package or file to the web app directly, you can publish it to a storage system that's accessible from the web app and trigger the app to pull the ZIP from the storage location.

The remote URL can be any publicly accessible location, but it's best to use a blob storage container with a shared access signature (SAS) key to protect it.

Use the az webapp deploy command like you would in the other sections, but use --src-url instead of --src-path. The following example uses the --src-url parameter to specify the URL of a ZIP file hosted in an Azure Storage account.

az webapp deploy --resource-group <group-name> --name <app-name> --src-url "https://storagesample.blob.core.windows.net/sample-container/myapp.zip?sv=2021-10-01&sb&sig=slk22f3UrS823n4kSh8Skjpa7Naj4CG3 --type zip

Invoke the Kudu publish API like you would in the other sections. Instead of uploading a file, pass in a JSON object with packageUri in the request body. The following examples use this method to specify the URL of a ZIP file hosted in an Azure Storage account. The type is still specified as a query string. If you choose basic authentication, supply the deployment credentials in <username> and <password>.

# Microsoft Entra authentication
TOKEN=$(az account get-access-token --query accessToken | tr -d '"')

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"packageUri": "https://storagesample.blob.core.windows.net/sample-container/myapp.zip?sv=2021-10-01&sb&sig=slk22f3UrS823n4kSh8Skjpa7Naj4CG3"}' \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=zip"

# Basic authentication
curl -X POST \
     -u '<username>:<password>' \
     -H "Content-Type: application/json" \
     -d '{"packageUri": "https://storagesample.blob.core.windows.net/sample-container/myapp.zip?sv=2021-10-01&sb&sig=slk22f3UrS823n4kSh8Skjpa7Naj4CG3"}' \
     "https://<app-name>.scm.azurewebsites.net/api/publish?type=zip"

Note

Get the actual fully qualified domain name to use in the URL from the note at the beginning of the article.

Add the following JSON to your ARM template. Replace the placeholder <app-name>.

{
    "type": "Microsoft.Web/sites/extensions",
    "apiVersion": "2021-03-01",
    "name": "onedeploy",
    "dependsOn": [
        "[resourceId('Microsoft.Web/Sites', <app-name>')]"
    ],
    "properties": {
        "packageUri": "<zip-package-uri>",
        "type": "<type>",
        "path": "<target-path>"
    }
}

Use the following reference to help you configure the properties:

Property	Description	Required
`packageUri`	The URI of the package or file. For more information, see Microsoft.Web sites/extensions 'onedeploy'.	Yes
`type`	See the `type` parameter in Kudu publish API reference.	Yes
`path`	See the `target-path` parameter in Kudu publish API reference.	No

Kudu publish API reference

The publish Kudu API allows you to specify the same parameters from the CLI command as URL query parameters. To authenticate with the Kudu REST API, we recommend token authentication, but you can also use basic authentication with your app's deployment credentials.

The following table shows the available query parameters, their allowed values, and descriptions.

Key	Allowed values	Description	Required	Type
`type`	`war`\|`jar`\|`ear`\|`lib`\|`startup`\|`static`\|`zip`	This is the type of the artifact being deployed. It sets the default target path and informs the web app how the deployment should be handled. `type=zip`: Deploy a ZIP package by unzipping the content to `/home/site/wwwroot`. `target-path` parameter is optional. `type=war`: Deploy a WAR package. By default, the WAR package is deployed to `/home/site/wwwroot/app.war`. The target path can be specified with `target-path`. `type=jar`: Deploy a JAR package to `/home/site/wwwroot/app.jar`. The `target-path` parameter is ignored. `type=ear`: Deploy an EAR package to `/home/site/wwwroot/app.ear`. The `target-path` parameter is ignored. `type=lib`: Deploy a JAR library file. By default, the file is deployed to `/home/site/libs`. The target path can be specified with `target-path`. `type=static`: Deploy a static file, such as a script. By default, the file is deployed to `/home/site/wwwroot`. `type=startup`: Deploy a script that App Service automatically uses as the startup script for your app. By default, the script is deployed to `D:\home\site\scripts\<name-of-source>` for Windows and `home/site/wwwroot/startup.sh` for Linux. The target path can be specified with `target-path`.	Yes	String
`restart`	`true`\|`false`	By default, the API restarts the app following the deployment operation (`restart=true`). When you deploy multiple artifacts, you can prevent restarts on all but the final deployment by setting `restart=false`.	No	Boolean
`clean`	`true`\|`false`	Specifies whether to clean (delete) the target deployment before deploying the artifact there.	No	Boolean
`ignorestack`	`true`\|`false`	The publish API uses the `WEBSITE_STACK` environment variable to choose safe defaults depending on your site's language stack. Setting this parameter to `false` disables any language-specific defaults.	No	Boolean
`target-path`	An absolute path	The absolute path to deploy the artifact to. For example, `/home/site/deployments/tools/driver.jar` or `/home/site/scripts/helper.sh`.	No	String

For more advanced deployment scenarios, try deploying to Azure with Git. Git-based deployment to Azure enables version control, package restore, MSBuild, and more.

Share via

Deploy files to Azure App Service

Prerequisites

Create a project ZIP package

Deploy a ZIP package

Deploy with ZIP deploy UI in Kudu

Deploy without ZIP deploy UI in Kudu

Enable build automation for ZIP deploy

Deploy WAR, JAR, or EAR packages

Deploy individual files

Deploy a startup script

Deploy a library file

Deploy a static file

Deploy to network-secured apps

Kudu publish API reference

Related content

Feedback

Additional resources