|
| 1 | +--- |
| 2 | +title: Publishing a Python app to Azure App Service on Windows |
| 3 | +description: How to publish a Python web application directly to Azure App Service on Windows from Visual Studio, including the necessary content for the web.config file. |
| 4 | +ms.date: 10/18/2018 |
| 5 | +ms.prod: visual-studio-dev15 |
| 6 | +ms.technology: vs-python |
| 7 | +ms.topic: conceptual |
| 8 | +author: kraigb |
| 9 | +ms.author: kraigb |
| 10 | +manager: douge |
| 11 | +ms.workload: |
| 12 | + - python |
| 13 | + - data-science |
| 14 | + - azure |
| 15 | +--- |
| 16 | + |
| 17 | +# Publishing to Azure App Service on Windows |
| 18 | + |
| 19 | +> [!Note] |
| 20 | +> This content and the features described are deprecated but continue to work. Python developers are encouraged to migrate to [App Service on Linux](publishing-python-web-applications-to-azure-from-visual-studio.md) where possible. |
| 21 | +
|
| 22 | +Visual Studio provides the capability to publish a Python web app directly to Azure App Service on Windows. Publishing to Azure App Service on Windows means copying the necessary files to the server and setting up an appropriate `web.config` file that instructs the web server how to launch your app. |
| 23 | + |
| 24 | +The publishing process differs between Visual Studio 2017 and Visual Studio 2015. Specifically, Visual Studio 2015 automates some of the steps, including the creation of `web.config`, but this automation limits long-term flexibility and control. Visual Studio 2017 requires more manual steps but provides more exact control over your Python environment. Both options are described here. |
| 25 | + |
| 26 | +> [!Note] |
| 27 | +> For background on the changes between Visual Studio 2015 and Visual Studio 2017, see the blog post, [Publish to Azure in Visual Studio 2017](https://blogs.msdn.microsoft.com/pythonengineering/2016/12/12/publish-to-azure-in-vs-2017/). |
| 28 | +
|
| 29 | +## Prerequisites |
| 30 | + |
| 31 | +For this walkthrough, you need a web app project based on the Bottle, Flask, or Django frameworks. If you don't yet have a project and would like to try the publishing process, create a simple test project as follows: |
| 32 | + |
| 33 | +1. In Visual Studio, select **File > New > Project**, search for "Bottle", select the **Bottle Web Project**, specify and name and a path for the project, click **OK**. (The Bottle template is included with the Python development workload; see [Installation](installing-python-support-in-visual-studio.md).) |
| 34 | + |
| 35 | +1. Follow the prompts to install external packages, selecting **Install into a virtual environment** and your preferred base interpreter for the virtual environment. You typically match this choice with the version of Python installed on App Service. |
| 36 | + |
| 37 | +1. Test the project locally by pressing F5 or selecting **Debug > Start Debugging**. |
| 38 | + |
| 39 | +## Create an Azure App Service |
| 40 | + |
| 41 | +Publishing to Azure requires a target App Service. For this purpose you can create an App Service using an Azure subscription, or you can use a temporary site. |
| 42 | + |
| 43 | +If you don't already have a subscription, start with a [free full Azure account](https://azure.microsoft.com/free/), which includes generous credits for Azure services. Also consider signing up for [Visual Studio Dev Essentials](https://azure.microsoft.com/pricing/member-offers/vs-dev-essentials/), which gives you $25 credit every month for a full year. |
| 44 | + |
| 45 | +> [!Tip] |
| 46 | +> Although Azure asks for a credit card to verify your account, the card is not charged. You can also set a [spending limit](/azure/billing/billing-spending-limit) equal to your free credits to guarantee that no extra charges occur. In addition, Azure provides a free App Service plan tier that's ideal for simple test apps as described in the next section. |
| 47 | +
|
| 48 | +### Using a subscription |
| 49 | + |
| 50 | +With an active Azure subscription, create an App Service with an empty Web App as follows: |
| 51 | + |
| 52 | +1. Sign in at [portal.azure.com](https://portal.azure.com). |
| 53 | +1. Select **+New**, then select **Web + Mobile** followed by **Web App**. |
| 54 | +1. Specify a name for the web app, leave **Resource Group** to "Create New", and choose **Windows** as the operating system. |
| 55 | +1. Select **App service plan/location**, select **Create new**, and specify a name and location. Then select **Pricing tier**, scroll down to and select the **F1 Free** plan, press **Select**, followed by **OK** and then **Create**. |
| 56 | +1. (Optional) Once the App Service has been created, navigate to it, select **Get publish profile**, and save the file locally. |
| 57 | + |
| 58 | +### Using a temporary App Service |
| 59 | + |
| 60 | +Create a temporary App Service without needing an Azure subscription as follows: |
| 61 | + |
| 62 | +1. Open your browser to [try.azurewebsites.net](https://try.azurewebsites.net). |
| 63 | +1. Select **Web App** for the app type, then select **Next**. |
| 64 | +1. Select **Empty Site**, followed by **Create**. |
| 65 | +1. Sign in with a social login of your choice, and after a short time your site is ready at the displayed URL. |
| 66 | +1. Select **Download publishing profile** and save the `.publishsettings` file, which you use later. |
| 67 | + |
| 68 | +## Configure Python on Azure App Service |
| 69 | + |
| 70 | +Once you have an App Service with an empty Web App running (either in your subscription or on a free site), install a chosen version of Python as described [Managing Python on Azure App Service](managing-python-on-azure-app-service.md). For publishing from Visual Studio 2017, record the exact path to the Python interpreter installed with the site extension as described in that article. |
| 71 | + |
| 72 | +If desired, you can also install the `bottle` package using the process in those instructions, as that package is installed as part of other steps in this walkthrough. |
| 73 | + |
| 74 | +## Publish to App Service - Visual Studio 2017 |
| 75 | + |
| 76 | +Publishing to Azure App Service from Visual Studio 2017 copies only the files in your project to the server. It's necessary, therefore, to create the necessary files to configure the server environment. |
| 77 | + |
| 78 | +1. In Visual Studio **Solution Explorer**, right-click the project and select **Add > New Item...*. In the dialog that appears, selecting the "Azure web.config (Fast CGI)" template and select OK. This creates a `web.config` file in your project root. |
| 79 | + |
| 80 | +1. Modify the `PythonHandler` entry in `web.config` so that the path matches the Python installation on the server (see [IIS Configuration Reference](https://www.iis.net/configreference) (iis.net) for exact details). For example, for Python 3.6.1 x64 the entry should appear as follows: |
| 81 | + |
| 82 | + ```xml |
| 83 | + <system.webServer> |
| 84 | + <handlers> |
| 85 | + <add name="PythonHandler" path="*" verb="*" modules="FastCgiModule" |
| 86 | + scriptProcessor="D:\home\Python361x64\python.exe|D:\home\Python361x64\wfastcgi.py" |
| 87 | + resourceType="Unspecified" requireAccess="Script"/> |
| 88 | + </handlers> |
| 89 | + </system.webServer> |
| 90 | + ``` |
| 91 | + |
| 92 | +1. Set the `WSGI_HANDLER` entry in `web.config` as appropriate for the framework you're using: |
| 93 | + |
| 94 | + - **Bottle**: add parentheses after `app.wsgi_app` as shown below. This is necessary because that object is a function (see `app.py`) rather than a variable: |
| 95 | + |
| 96 | + ```xml |
| 97 | + <!-- Bottle apps only --> |
| 98 | + <add key="WSGI_HANDLER" value="app.wsgi_app()"/> |
| 99 | + ``` |
| 100 | + |
| 101 | + - **Flask**: Change the `WSGI_HANDLER` value to `<project_name>.app` where `<project_name>` matches the name of your project. You can find the exact identifer by looking at the `from <project_name> import app` statement in the `runserver.py`. For example, if the project is named "FlaskAzurePublishExample", the entry would appear as follows: |
| 102 | + |
| 103 | + ```xml |
| 104 | + <!-- Flask apps only: change the project name to match your app --> |
| 105 | + <add key="WSGI_HANDLER" value="FlaskAzurePublishExample.app"/> |
| 106 | + ``` |
| 107 | + |
| 108 | + - **Django**: Two changes are needed to `web.config` for Django projects. First, change the `WSGI_HANDLER` value to `django.core.wsgi.get_wsgi_application()` (the object is in the `wsgi.py` file): |
| 109 | + |
| 110 | + ```xml |
| 111 | + <!-- Django apps only --> |
| 112 | + <add key="WSGI_HANDLER" value="django.core.wsgi.get_wsgi_application()"/> |
| 113 | + ``` |
| 114 | + |
| 115 | + Second, add the following entry below the one for `WSGI_HANDLER`, replacing `DjangoAzurePublishExample` with the name of your project: |
| 116 | + |
| 117 | + ```xml |
| 118 | + <add key="DJANGO_SETTINGS_MODULE" value="DjangoAzurePublishExample.settings" /> |
| 119 | + ``` |
| 120 | + |
| 121 | +1. **Django apps only**: In the Django project's `settings.py` file, add your site URL domain to `ALLOWED_HOSTS` as shown below, replacing 'vspython-test-02.azurewebsites.net' with your URL, of course: |
| 122 | + |
| 123 | + ```python |
| 124 | + # Change the URL to your specific site |
| 125 | + ALLOWED_HOSTS = ['vspython-test-02.azurewebsites.net'] |
| 126 | + ``` |
| 127 | + |
| 128 | + Failure to add your URL to the array results in the error "DisallowedHost at / Invalid HTTP_HOST header: '\<site URL\>'. You may need to add '\<site URL\>' to ALLOWED_HOSTS." |
| 129 | + |
| 130 | + Note that when the array is empty, Django automatically allows 'localhost', but adding your production URL removes that capabilities. For this reason you might want to maintain separate development and production copies of `settings.py`, or use environment variables to control the run time values. |
| 131 | + |
| 132 | +1. In **Solution Explorer**, expand the folder named the same as your project, right-click the `static` folder, select **Add > New Item...**, select the "Azure static files web.config" template, and select **OK**. This action creates another `web.config` in the `static` folder that disables Python processing for that folder. This configuration sends requests for static files to the default web server rather than using the Python application. |
| 133 | + |
| 134 | +1. Save your project, then in Visual Studio **Solution Explorer**, right-click the project and select **Publish**. |
| 135 | + |
| 136 | +  |
| 137 | + |
| 138 | +1. In the **Publish** tab that appears, select the publishing target: |
| 139 | + |
| 140 | + a. Your own Azure subscription: select **Microsoft Azure App Service**, then **Select Existing** followed by **Publish**. A dialog appears in which you can select the appropriate subscription and app service. If the App Service doesn't appear, use the downloaded publishing profile as described below for a temporary APp Service. |
| 141 | + |
| 142 | +  |
| 143 | + |
| 144 | + b. If you're using a temporary App Service on try.azurewebsites.net, or otherwise need to use a publishing profile, select the **>** control to find **Import profile**, select that option, then select **Publish**. This prompts for the location of the `.publishsettings` file downloaded earlier. |
| 145 | + |
| 146 | +  |
| 147 | + |
| 148 | +1. Visual Studio displays publishing status in a "Web Publish Activity" window and the Publish window. Once publishing is complete, the default browser opens on the site URL. The URL is also shown in the Publish window. |
| 149 | + |
| 150 | +1. When the browser opens, you may see the message, "The page cannot be displayed because an internal server error has occurred." This message indicates that your Python environment on the server is not fully configured, in which case do the following steps: |
| 151 | + |
| 152 | + a. Refer again to [Managing Python on Azure App Service](managing-python-on-azure-app-service.md), making sure that you have an appropriate Python site extension installed. |
| 153 | + |
| 154 | + b. Double-check the path to the Python interpreter in your `web.config` file. The path must exactly match the install location of your chosen site extension. |
| 155 | + |
| 156 | + c. Use the Kudu console to upgrade any packages listed in your app's `requirements.txt` file: navigate to the same Python folder that's used in `web.config`, such as `/home/python361x64`, and run the following command as described in the [Kudu console](managing-python-on-azure-app-service.md#azure-app-service-kudu-console) section: |
| 157 | + |
| 158 | + ```command |
| 159 | + python -m pip install --upgrade -r /home/site/wwwroot/requirements.txt |
| 160 | + ``` |
| 161 | + |
| 162 | + If you see permission errors when running this command, double-check that you're running the command in your site extension folder and *not* in the folder of one of App Service's default Python installations. Because you can't modify those default environments, attempting to install packages certainly fails. |
| 163 | + |
| 164 | + d. For detailed error output, add the following line to `web.config` within the `<system.webServer>` node, which provides more detailed error output: |
| 165 | + |
| 166 | + ```xml |
| 167 | + <httpErrors errorMode="Detailed"></httpErrors> |
| 168 | + ``` |
| 169 | + |
| 170 | + e. Try restarting the App Service after installing new packages. A restart is not necessary when changing `web.config`, as App Service does an automatic restart whenever `web.config` changes. |
| 171 | + |
| 172 | + > [!Tip] |
| 173 | + > If you make any changes to your app's `requirements.txt` file, be sure to again use the Kudu console to install any packages that are now listed in that file. |
| 174 | + |
| 175 | +1. Once you've fully configured the server environment, refresh the page in the browser and the web app should appear. |
| 176 | + |
| 177 | +  |
| 178 | + |
| 179 | +## Publishing to App Service - Visual Studio 2015 |
| 180 | + |
| 181 | +> [!Note] |
| 182 | +> A short video of this process can be found on [Visual Studio Python Tutorial: Building a Website](https://www.youtube.com/watch?v=FJx5mutt1uk&list=PLReL099Y5nRdLgGAdrb_YeTdEnd23s6Ff&index=6) (youtube.com, 3m10s). |
| 183 | + |
| 184 | +1. In **Solution Explorer**, right-click the project select **Publish**. |
| 185 | + |
| 186 | +1. In the **Publish** dialog, select **Microsoft Azure App Service**: |
| 187 | + |
| 188 | +  |
| 189 | + |
| 190 | +1. Select a target: |
| 191 | + |
| 192 | + - If you have an Azure subscription, select **Microsoft Azure App Service** as the publishing target, then in the following dialog select an existing App Service or select **New** to create a new one. |
| 193 | + - If you're using a temporary site from try.azurewebsites.net, select **Import** as the publishing target, then browse for the `.publishsettings` file downloaded from the site and select **OK**. |
| 194 | + |
| 195 | +1. The App Service details appear in the **Publish** dialog's **Connection** tab below. |
| 196 | + |
| 197 | +  |
| 198 | + |
| 199 | +1. Select **Next >** as needed to review additional settings. |
| 200 | + |
| 201 | +1. Select **Publish**. Once your application is deployed to Azure, your default browser opens on that site. |
| 202 | + |
| 203 | +As part of this process, Visual Studio also does the following steps: |
| 204 | + |
| 205 | +- Create a `web.config` file on the server that contains appropriate pointers to the app's `wsgi_app` function and to App Service's default Python 3.4 interpreter. |
| 206 | +- Turn off processing for files in the project's `static` folder (rules for this are in `web.config`). |
| 207 | +- Publish the virtual environment to the server. |
| 208 | +- Add a `web.debug.config` file and the ptvsd debugging tools to enable remote debugging. |
| 209 | + |
| 210 | +As noted earlier, these automatic steps simplify the publishing process but make it more difficult to control the Python environment. For example, the `web.config` file is created only on the server but not added to your project. The publishing process also takes longer because it's copying the whole virtual environment from your development computer rather than relying on the server configuration. |
| 211 | + |
| 212 | +Eventually you may want to maintain your own `web.config` file and use `requirements.txt` to maintain packages on the server directly. Using `requirements.txt`, in particular, guarantees that your development and server environments always match. |
0 commit comments