Deploy your app to Azure App Service using FTP/S

Article
02/29/2024

This article shows you how to use FTP or FTPS to deploy your web app, mobile app backend, or API app to Azure App Service.

The FTP/S endpoint for your app is already active. No configuration is necessary to enable FTP/S deployment.

Note

When FTP basic authentication is disabled, FTP/S deployment doesn't work, and you can't view or configure FTP credentials in the app's Deployment Center.

Get deployment credentials

Follow the instructions at Configure deployment credentials for Azure App Service to copy the application-scope credentials or set the user-scope credentials. You can connect to the FTP/S endpoint of your app using either credentials.
Craft the FTP username in the following format, depending on your choice of credential scope:

Application-scope User-scope

<app-name>\$<app-name> <app-name>\<deployment-user>

In App Service, the FTP/S endpoint is shared among apps. Because the user-scope credentials aren't linked to a specific resource, you need to prepend the user-scope username with the app name as shown above.

Application-scope	User-scope
`<app-name>\$<app-name>`	`<app-name>\<deployment-user>`

Get FTP/S endpoint

In the same management page for your app where you copied the deployment credentials (Deployment Center > FTP Credentials), copy the FTPS endpoint.

Run the az webapp deployment list-publishing-profiles command. The following example uses a JMESPath query to extract the FTP/S endpoints from the output.

az webapp deployment list-publishing-profiles --name <app-name> --resource-group <group-name> --query "[?ends_with(profileName, 'FTP')].{profileName: profileName, publishUrl: publishUrl}"

Each app has two FTP/S endpoints, one is read-write, while the other is read-only (profileName contains ReadOnly) and is for data recovery scenarios. To deploy files with FTP, copy the URL of the read-write endpoint.

Run the Get-AzWebAppPublishingProfile command. The following example extracts the FTP/S endpoint from the XML output.

$xml = [xml](Get-AzWebAppPublishingProfile -Name <app-name> -ResourceGroupName <group-name> -OutputFile null)
$xml.SelectNodes("//publishProfile[@publishMethod=`"FTP`"]/@publishUrl").value

Deploy files to Azure

From your FTP client (for example, Visual Studio, Cyberduck, or WinSCP), use the connection information you gathered to connect to your app.
Copy your files and their respective directory structure to the /site/wwwroot directory in Azure (or the /site/wwwroot/App_Data/Jobs/ directory for WebJobs).
Browse to your app's URL to verify the app is running properly.

Note

Unlike Git-based deployments and Zip deployment, FTP deployment doesn't support build automation, such as:

dependency restores (such as NuGet, NPM, PIP, and Composer automations)
compilation of .NET binaries
generation of web.config (here is a Node.js example)

Generate these necessary files manually on your local machine, and then deploy them together with your app.

Enforce FTPS

For enhanced security, you should allow FTP over TLS/SSL only. You can also disable both FTP and FTPS if you don't use FTP deployment.

In your app's resource page in Azure portal, select Configuration > General settings from the left navigation.
To disable unencrypted FTP, select FTPS Only in FTP state. To disable both FTP and FTPS entirely, select Disabled. When finished, select Save. If using FTPS Only, you must enforce TLS 1.2 or higher by navigating to the TLS/SSL settings page of your web app. TLS 1.0 and 1.1 aren't supported with FTPS Only.

Run the az webapp config set command with the --ftps-state argument.

az webapp config set --name <app-name> --resource-group <group-name> --ftps-state FtpsOnly

Possible values for --ftps-state are AllAllowed (FTP and FTPS enabled), Disabled (FTP and FTPs disabled), and FtpsOnly (FTPS only).

Run the Set-AzWebApp command with the -FtpsState parameter.

Set-AzWebApp -Name <app-name> -ResourceGroupName <group-name> -FtpsState FtpsOnly

Possible values for --ftps-state are AllAllowed (FTP and FTPS enabled), Disabled (FTP and FTPs disabled), and FtpsOnly (FTPS only).

What happens to my app during deployment?

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. So the deployment can fail because of locked files. The app might also behave unpredictably during deployment because the files aren't all updated at the same time. This behavior is undesirable for a customer-facing app. There are a few ways to avoid these issues:

Run your app directly from the ZIP package, without unpacking it.
Stop your app or enable offline mode for it during deployment. For more information, see Deal with locked files during deployment.
Deploy to a staging slot with auto swap turned on.

Troubleshoot FTP deployment

How can I troubleshoot FTP deployment?
I'm not able to FTP and publish my code. How can I resolve the issue?
How can I connect to FTP in Azure App Service via passive mode?
Why is my connection failing when attempting to connect over FTPS using explicit encryption?
How can I determine the method that was used to deploy my Azure App Service?

How can I troubleshoot FTP deployment?

The first step for troubleshooting FTP deployment is isolating a deployment issue from a runtime application issue.

A deployment issue typically results in no files or wrong files deployed to your app. You can troubleshoot by investigating your FTP deployment or selecting an alternate deployment path (such as source control).

A runtime application issue typically results in the right set of files deployed to your app but incorrect app behavior. You can troubleshoot by focusing on code behavior at runtime and investigating specific failure paths.

To determine a deployment or runtime issue, see Deployment vs. runtime issues.

I'm not able to FTP and publish my code. How can I resolve the issue?

Check that you entered the correct hostname and credentials. Check also that the following FTP ports on your machine aren't blocked by a firewall:

FTP control connection port: 21, 990
FTP data connection port: 989, 10001-10300

How can I connect to FTP in Azure App Service via passive mode?

Azure App Service supports connecting via both Active and Passive mode. Passive mode is preferred because your deployment machines are usually behind a firewall (in the operating system or as part of a home or business network). See an example from the WinSCP documentation.

Why is my connection failing when attempting to connect over FTPS using explicit encryption?

FTPS allows establishing the TLS secure connection in either an Explicit or Implicit way.

If you connect with Implicit encryption, the connection is established via port 990.
If you connect with Explicit encryption, the connection is established via port 21.

The URL format you use can affect your connection success, and it also depends on the client application you use. The portal shows the URL as ftps://, but note:

If the URL you connect with starts with ftp://, the connection is implied to be on port 21.
If it starts with ftps://, the connection is implied to be Implicit and on port 990.

Make sure not to mix both, such as attempting to connect to ftps:// and using port 21, as it will fail to connect, even if you wish to do Explicit encryption. This is due to an Explicit connection starting as a plain FTP connection before the AUTH method.

How can I determine the method that was used to deploy my Azure App Service?

You can find out how an app was deployed by checking the application settings. If the app was deployed using an external package URL, you should see the WEBSITE_RUN_FROM_PACKAGE setting in the application settings with a URL value. Or if it was deployed using zip deploy, you should see the WEBSITE_RUN_FROM_PACKAGE setting with a value of 1. If the app was deployed using Azure DevOps, you should see the deployment history in the Azure DevOps portal. If Azure Functions Core Tools is used, you should see the deployment history in the Azure portal.

Share via