Python in a container

In this tutorial, you will learn how to:

• Create aDockerfile file describing a simple Python container.
• Build, run, and verify the functionality of aDjango,Flask, or General Python app.
• Debug the app running in a container.

Prerequisites

• Install Docker on your machine and add it to the system path.

• On Linux, you should alsoenable Docker CLI for the non-root user account that will be used to run VS Code.

• The Container Tools extension. To install the extension, open the Extensions view (⇧⌘X (Windows, LinuxCtrl+Shift+X)), search forcontainer tools to filter results and select the Container Tools extension authored by Microsoft.

  

Create a Python project

If you don't have a Python project already, follow the tutorialGetting started with Python.

Note: If you want to containerize a complete Django or Flask web app, you can start with one of the following samples:

• python-sample-vscode-django-tutorial, which is the result of following theDjango Tutorial

• python-sample-vscode-flask-tutorial, which is the result of following theFlask Tutorial

Note: For this tutorial, be sure to use thetutorial branch of the sample repos.

After verifying your app runs properly, you can now containerize your application.

Add Docker files to the project

1. Open the project folder in VS Code.

2. Open theCommand Palette (⇧⌘P (Windows, LinuxCtrl+Shift+P)) and chooseContainers: Add Docker Files to Workspace...:

   

3. When prompted for the app type, selectPython: Django,Python: Flask, orPython: General as the app type. For this tutorial, we'll focus on thePython: General case, but will also include notes for Django and Flask.

4. Enter the relative path to the app's entry point. This excludes the workspace folder you start from. If you created a python app withhello.py according to theGetting Started with Python tutorial, choose that.

   Django: Choosemanage.py (root folder) orsubfolder_name/manage.py. See theofficial Django documentation.

   Flask: Choose the path to where you create your Flask instance. See theofficial Flask documentation.

   Tip: You may also enter the path to a folder name as long as this folder includes a__main__.py file.

5. Select the port number. We recommend selecting port 1024 or above to mitigate security concerns fromrunning as a root user. Any unused will port, but Django and Flask use standard default ports.

   Django: The default port 8000.

   Flask: The default port is 5000.

6. When prompted to include Docker Compose, selectNo if you do not want a Docker Compose file. If you selectYes, you will need to verify the path to yourwsgi.py file in theDockerfile to run theCompose Up command successfully. Compose is typically used when running multiple containers at once.

7. With all this information, the Container Tools extension creates the following files:

   • ADockerfile. To learn more about IntelliSense in this file, refer to theoverview.

   • A.dockerignore file to reduce the image size by excluding files and folders that aren't needed such as.git,.vscode, and__pycache__.

   • If you're using Docker Compose, adocker-compose.yml anddocker-compose.debug.yml file.

   • If one does not already exist, arequirements.txt file for capturing all app dependencies.

   Important Note: To use our setup, the Python framework (Django/Flask) and Gunicornmust be included in therequirements.txt file. If the virtual environment/host machine already has these prerequisites installed and is supposed to be identical to the container environment, ensure app dependencies are ported over by runningpip freeze > requirements.txt in the terminal.This will overwrite your currentrequirements.txt file.

(Optional) Add an environment variable to the image

This step is not required, but it is included to help you understand how to add environment variables that need to be set in the container's environment.

The Container Tools extension helps you author Dockerfiles by usingIntelliSense to provide auto-completions and contextual help. To see this feature in action:

1. Open theDockerfile.

2. Underneath theEXPOSE statement, type⌃Space (Windows, LinuxCtrl+Space) to trigger IntelliSense and scroll toENV.

   

3. PressTab orEnter to complete the statement, then set thekey to the name of the variable, and set thevalue.

For more information about setting and using environment variables in the Dockerfile, see theENV instruction andEnvironment replacement section in the Docker documentation.

Gunicorn modifications for Django and Flask apps

To give Python web developers a great starting point, we chose to useGunicorn as the default web server. Since it is referenced in the default Dockerfile, it is included as a dependency in therequirements.txt file. If you don't see it inrequirements.txt, runpip install gunicorn and then runpip freeze > requirements.txt to regenerate therequirements.txt file.

• Django: To use Gunicorn, it must bind to an application callable (what the application server uses to communicate with your code) as an entry point. This callable is declared in thewsgi.py file of a Django application. To accomplish this binding, the final line in the Dockerfile says:

  CMD ["gunicorn","--bind","0.0.0.0:8000","{workspace_folder_name}.wsgi"]

  If your project does not follow Django's default project structure (that is, a workspace folder and a wsgi.py file >within a subfolder named the same as the workspace) you must overwrite the Gunicorn entry point in the Dockerfile to locate the correctwsgi.py file.

  If yourwsgi.py file is in the root folder, the final argument in the command above will be"wsgi". Within subfolders, the argument would be"subfolder1_name.subfolder2_name.wsgi".

• Flask: To use Gunicorn, it must bind to an application callable (what the application server uses to communicate with your code) as an entry point. This callable corresponds with thefile location andvariable name of your created Flask instance. According toofficial Flask Documentation, users generally create a Flask instance in the main module or in the__init__.py file of their package in this manner:

  from flaskimport Flaskapp = Flask(__name__)# Flask instance named app

  To accomplish this binding, the final line in the Dockerfile says:

  CMD ["gunicorn","--bind","0.0.0.0:5000","{subfolder}.{module_file}:app"]

  During theContainers: Add Docker Files to Workspace... command, you configure the path to the Flask instance, however, the Container Tools extension assumes your Flask instance variable is namedapp. If this is not the case, you must change the variable name in the Dockerfile.

  If your main module was in the root folder as a file namedmain.py and had a Flask instance variable was namedmyapp, the final argument in the command above will be"main:myapp". Within subfolders, the argument would be"subfolder1_name.subfolder2_name.main:myapp".

Build, run, and debug the container

TheContainers: Add Docker Files to Workspace... command automatically creates a Docker launch configuration to build and run your container in debug mode. To debug your Python app container:

1. Navigate to the file that contains your app's startup code, and set a breakpoint.

2. Navigate toRun and Debug and selectContainers: Python - General,Containers: Python - Django, orContainers: Python - Flask, as appropriate.

   

3. Start debugging using theF5 key.

   • The container image builds.
   • The container runs.
   • The python debugger stops at the breakpoint.

4. Step over this line once.

5. When ready, press continue.

The Container Tools extension will launch your browser to a randomly mapped port:

Tip: To modify your Docker build settings, such as changing the image tag, navigate to.vscode -> tasks.json under thedockerBuild attribute in thedocker-build task. Use IntelliSense within the file (⌃Space (Windows, LinuxCtrl+Space)) to display all other valid directives.

Use the Container Explorer

The Container Explorer provides an interactive experience to examine and manage container assets such as containers, images, and so on. To see an example:

1. Navigate to the Container Explorer.

2. In theContainers tab, right-click on your container and chooseView Logs.

   

3. The output will be displayed in the terminal.

Build the image in Azure

You can use the commandAzure Container Registry: Build Image in Azure to build an image that you can then deploy to Azure App Service or Azure Container Apps.

1. Install theAzure Resources extension. Open theCommand Palette (⇧⌘P (Windows, LinuxCtrl+Shift+P)) and search for the commandAzure: Sign In. If you don't have an Azure account, you can sign up for afree trial.

2. There are two ways to invoke the build in Azure command. You can right-click on the Dockerfile, and chooseBuild Image in Azure. You can also use theCommand Palette (⇧⌘P (Windows, LinuxCtrl+Shift+P)) and search for the commandAzure Container Registry: Build Image in Azure.

   

3. Choose the name and tag for the built image. You'll use this to identify it in the container registry.

   

4. Choose the Azure subscription you want to use.

5. Choose an existing Azure Container Registry, or create a new one. When you create a new one, you're asked to provide the name, resource group, location, and an option for pricing, such as Basic, Standard, or Premium. You can read about the costs of these options atPricing - Container Registry.

6. Specify the base OS, Linux or Windows. This choice must be consistent with the Dockerfile.

   

The process of building the image might take a few minutes. You can track progress in the terminal. If you encounter an error (Error: failed to download context.), try using theRefresh option on the container registry and then request another build. Before rebuilding, manually delete the old image.

Deploy to Azure App Service or Azure Container Apps

Once the container image is built, it should appear in the Container Registry with the tag you specified. Now that it's built, you can deploy it to Azure App Service or Azure Container Apps. TheAzure App Service extension is recommended for deployments to Azure App Service, and theAzure Container Apps extension is required for deployments to Azure Container Apps. You can obtain both if you install theAzure Tools extension pack, which includes a package of tools for a wide range of Azure development scenarios.

1. Right-click on the image tag and chooseDeploy Image to Azure App Service orDeploy Image to Azure Container Apps.

   

2. Provide the name of the web site. This must be a unique name, and for Django apps, it must also be listed as a valid host name in theALLOWED_HOSTS list in thesettings.py file.

3. Provide a resource group, location, and App Service Plan. If you're just getting started, you can choose the free plan.

4. The image is deployed; the process might take a few minutes. Once it's deployed, a notification appears with a button you can use to access the site. You can also use the site's address,{appname}.azurewebsites.net where{appname} is the name you gave when creating it. If it doesn't work at first, try again in a few minutes. It's not uncommon for the first few attempts to time out or return an error. It just means the App Service isn't ready yet to receive requests.

5. Make a small change in the application code that's visible on one of the pages, and save the file.

6. Use the Azure icon to open theResources view, and expand the node for your subscription to find the App Service that you deployed in the previous step.

7. Right-click on the App Service node and look at the available options. ChooseDeploy to Web App, and then specify your app folder to deploy it.

   

   When warned that this will overwrite the previous deployment, chooseDeploy to confirm.

   This might take a few minutes; you can monitor progress in the terminal window. When it finishes, a button with access to the site is given.

   

   Use the button and verify that your change is reflected on the site.

Congratulations, you've used Python in VS Code to create an deploy a web site that's hosted in the cloud and live on the internet!

Free up resources

In theAzure portal, delete the Resource Group to free up all resources that you created during this exercise.

Next steps

You're done! Now that your container is ready, you may want to:

• Learn about using Docker Compose
• Debug with Docker Compose
• Customize how you debug Python apps in a container
• Customize your Docker build and run tasks
• Push your Django image to an Azure Container Registry
• Deploy to Azure Container Apps