Back in August we had a blog post on using newer versions of Python on Azure App Service. In that post we outlined why we were working on this alternative approach to using Python on Azure App Service and provided basic templates of key files you needed to make the approach work. While that approach still works, we realized there were some steps that more arduous than necessary which were common to all websites using Azure Web Apps.
Our search to simplify the creation of an Azure Web App using a new release of Python led us to the Cookiecutter project. We realized that a lot of the steps in getting started involved creating files that were mostly boilerplate with only small details that were custom to any specific web app. All of this led us to create a Cookiecutter template for using Python with Azure Web Apps.
Using the template
You have two options when it comes to using a Cookiecutter template. If you Visual Studio “15” then you can use the new Cookiecutter Explorer. The other option is to use the command-line version of Cookiecutter (installing Cookiecutter is covered by the project's documentation).
The questions that Cookiecutter will ask you about for the Web Apps template should be self-explanatory and have reasonable defaults where possible. If you're using the Cookiecutter Explorer then there is a helpful description if you hover over a field, otherwise you can read the
README.md file for the template for explanations. The one question, though, which might not be quite so obvious is the
site_type question. That refers to whether you plan to have a web app which uses a WSGI server or a socket-based server. Which you choose is up to you and will depend on what web framework you choose for your web app. The expectation is that if you need direct access to the listening socket for your web server you will choose the socket option, otherwise you will choose WSGI.
One neat thing to realize is that thanks to our Python 3.5 support, you can choose the socket option and use Python's
await syntax in your web app! We hope you do give this a try as we have found the new syntax makes it much easier to write performant asynchronous code than the old way with callbacks (we're also somewhat proud to be supporting Python 3.5 before some other PaaS providers 😉). If you want to try the new syntax but don't know where to start, we suggest looking at aiohttp as a production-ready web framework/server to get started with.
What the template gives you
Once you have gone through and answered the questions for Cookiecutter you will end up with a directory containing a bunch of files. Some you will want to edit to make the web app your own, while others you should never have to touch. The generated
README.md file in the output directory explains which each file is meant for.
There are a few things to be aware of about the generated files. One is that you should edit the main module and the requirements file that were generated (Cookiecutter asked you what to name these files, but the defaults are
requirements.txt, respectively). While a default web app is provided for easy testing that your deployment worked, you will want to edit your main module to use whatever production-grade server you choose to use, e.g. aiohttp's server. You will also want to edit your requirements file to list what projects to download from PyPI for your web app, e.g.
Two, if you are using the socket option, do remember what environment variable you specified for storing the listening port in (the default is
PORT). You can then use e.g.
os.environ["PORT"] to get the listening port for your server.
Finally, the configuration files that were generated for you set up your web app to automatically run pip after every deployment. Pip is run with
--upgrade, so do make sure to properly specify your version dependencies in your requirements file, otherwise your dependencies may get updated unexpectedly to a version which your code isn't compatible with.
Deploying your new Web App
There are two parts to deploying to Azure Web Apps using the template: deploying the generated ARM template and deploying your files.
Deploying the ARM template
Azure Resource Manager uses files called ARM templates to provision resources on Azure. Since you're provisioning an Azure Web App we generated an ARM template file named
azuredeploy.json as part of your Cookiecutter template. Using the ARM template will set everything up based on the answers you gave to Cookiecutter.
There are multiple ways to deploy an ARM template, but probably the simplest for one-off deployments is to deploy using the Azure portal (specifically the "Deploy resources from custom template" section of those instructions). When it asks you to edit JSON for your deployment just paste in the contents of
azuredeploy.json and then fill out the template details that gets asked of you. After you click Create you just need to wait a few minutes and then your Azure Web App will be provisioned!
If you are looking for repeatable or scriptable deployments using ARM templates, the Azure CLI 2.0 (preview) tool can already do it (and it's written in Python!), or you can use the Azure SDK for Python to script the deployment process yourself.
Deploying your files
Once your web app is deployed you then need to get your files into the service. There are multiple options for deploying your files to Azure App Service, including a folder created in a cloud storage provider, IDEs, or git. Choose which ever one you prefer and set it up for your web app to get your files deployed.
Checking that everything worked
Obviously one way to check if everything worked is after you deploy your files and Azure says it's finished is to visit your website. But if you want a more thorough check you can access the Kudu service for your web app. There you will find a web console to browse the files in your web app, including logs. Once your latest deployment is finished you can look at the logs and see things like the output from pip to make sure everything worked the way you expected.
We want your feedback!
If you do use the Cookiecutter template, please let us know by leaving a comment! And if you find any bugs then please file an issue. Based on the positive/negative feedback we receive will decide whether to promote the template into a more official project on GitHub.
If you would like to develop your own templates and have them appear in Cookiecutter Explorer, it is as simple as publishing your template to GitHub, include "cookiecutter" in the repository name, and it will appear almost immediately in the search results.