Run a custom container in Azure

Azure App Service provides pre-defined application stacks on Windows like ASP.NET or Node.js, running on IIS. The preconfigured Windows container environment locks down the operating system from administrative access, software installations, changes to the global assembly cache, and so on. For more information, see Operating system functionality on Azure App Service. If your application requires more access than the preconfigured environment allows, you can deploy a custom Windows container instead.

This quickstart shows how to deploy an ASP.NET app, in a Windows image, to Docker Hub from Visual Studio. You run the app in a custom container in Azure App Service.


Windows Containers is limited to Azure Files and does not currently support Azure Blob.


To complete this tutorial:

Create an ASP.NET web app

Create an ASP.NET web app by following these steps:

  1. Open Visual Studio and then select Create a new project.

  2. In Create a new project, find and choose ASP.NET Web Application (.NET Framework) for C#, then select Next.

  3. In Configure your new project, name the application myfirstazurewebapp, and then select Create.

    Configure your web app project

  4. You can deploy any type of ASP.NET web app to Azure. For this quickstart, choose the MVC template.

  5. Select Docker support, and make sure authentication is set to No Authentication. Select Create.

    Create ASP.NET Web Application

  6. If the Dockerfile file isn't opened automatically, open it from the Solution Explorer.

  7. You need a supported parent image. Change the parent image by replacing the FROM line with the following code and save the file:

  8. From the Visual Studio menu, select Debug > Start Without Debugging to run the web app locally.

    Run app locally

Publish to Docker Hub

  1. In Solution Explorer, right-click the myfirstazurewebapp project and select Publish.

  2. Choose App Service and then select Publish.

  3. In Pick a publish target, select Container Registry and Docker Hub, and then click Publish.

    Publish from project overview page

  4. Supply your Docker Hub account credentials and select Save.

    Wait for the deployment to complete. The Publish page now shows the repository name to use later.

    Screenshot that highlights the repository name.

  5. Copy this repository name for later.

Create a Windows container app

  1. Sign in to the Azure portal.

  2. Choose Create a resource in the upper left-hand corner of the Azure portal.

  3. Under Popular services, select Create under Web App.

  4. In Create Web App, choose your subscription and a Resource Group. You can create a new resource group if needed.

  5. Provide an app name, such as win-container-demo. Choose Docker Container for Publish and Windows for Operating System. Select Next: Docker to continue.

    Create a Web App for Containers

  6. For Image Source, choose Docker Hub and for Image and tag, enter the repository name you copied in Publish to Docker Hub.

    Configure your a Web App for Containers

    If you have a custom image elsewhere for your web application, such as in Azure Container Registry or in any other private repository, you can configure it here.

  7. Select Review and Create and then Create and wait for Azure to create the required resources.

Browse to the container app

When the Azure operation is complete, a notification box is displayed.

Deployment succeeded

  1. Click Go to resource.

  2. In the overview of this resource, follow the link next to URL.

A new browser page opens to the following page:

Windows Container App Starting

Wait a few minutes and try again, until you get the default ASP.NET home page:

Windows Container App running

Congratulations! You're running your first custom Windows container in Azure App Service.

See container start-up logs

It may take some time for the Windows container to load. To see the progress, navigate to the following URL by replacing <app_name> with the name of your app.


The streamed logs looks like this:

2018-07-27T12:03:11  Welcome, you are now connected to log-streaming service.
27/07/2018 12:04:10.978 INFO - Site: win-container-demo - Start container succeeded. Container: facbf6cb214de86e58557a6d073396f640bbe2fdec88f8368695c8d1331fc94b
27/07/2018 12:04:16.767 INFO - Site: win-container-demo - Container start complete
27/07/2018 12:05:05.017 INFO - Site: win-container-demo - Container start complete
27/07/2018 12:05:05.020 INFO - Site: win-container-demo - Container started successfully

Update locally and redeploy

  1. In Visual Studio, in Solution Explorer, open Views > Home > Index.cshtml.

  2. Find the <div class="jumbotron"> HTML tag near the top, and replace the entire element with the following code:

    <div class="jumbotron">
        <h1>ASP.NET in Azure!</h1>
        <p class="lead">This is a simple app that we've built that demonstrates how to deploy a .NET app to Azure App Service.</p>
  3. To redeploy to Azure, right-click the myfirstazurewebapp project in Solution Explorer and choose Publish.

  4. On the publish page, select Publish and wait for publishing to complete.

  5. To tell App Service to pull in the new image from Docker Hub, restart the app. Back in the app page in the portal, click Restart > Yes.

    Restart web app in Azure

Browse to the container app again. As you refresh the webpage, the app should revert to the "Starting up" page at first, then display the updated webpage again after a few minutes.

Updated web app in Azure

Next steps

Or, check out other resources:

App Service on Linux provides pre-defined application stacks on Linux with support for languages such as .NET, PHP, Node.js and others. You can also use a custom Docker image to run your web app on an application stack that is not already defined in Azure. This quickstart shows you how to deploy an image from an Azure Container Registry (ACR) to App Service.


Create a container registry

This quickstart uses Azure Container Registry as the registry of choice. You're free to use other registries, but the steps may differ slightly.

Create a container registry by following the instructions in Quickstart: Create a private container registry using the Azure portal.


Be sure to set the Admin User option to Enable when you create the Azure container registry. You can also set it from the Access keys section of your registry page in the Azure portal. This setting is required for App Service access. For managed identity, see Deploy from ACR tutorial.

Sign in

  1. Launch Visual Studio Code.

  2. Select the Azure logo in the Activity Bar, navigate to the APP SERVICE explorer, then select Sign in to Azure and follow the instructions.

    sign in to Azure

  3. In the Status Bar at the bottom, verify your Azure account email address. In the APP SERVICE explorer, your subscription should be displayed.

  4. In the Activity Bar, select the Docker logo. In the REGISTRIES explorer, verify that the container registry you created appears.

    Screenshot shows the Registries value with Azure expanded.

Check prerequisites

Verify that you have Docker installed and running. The following command will display the Docker version if it is running.

docker --version

Create and build image

  1. In Visual Studio Code, open an empty folder and add a file called Dockerfile. In the Dockerfile, paste in the content based on your desired language framework:



ENTRYPOINT ["dotnet", "/defaulthome/hostingstart/hostingstart.dll"]

In this Dockerfile, the parent image is one of the built-in .NET containers of App Service. You can find the source files for it in the Azure-App-Service/ImageBuilder GitHub repository, under GenerateDockerFiles/dotnetcore. Its Dockerfile copies a simple .NET app into /defaulthome/hostingstart. Your Dockerfile simply starts that app.

  1. Open the Command Palette, and type Docker Images: Build Image. Type Enter to run the command.

  2. In the image tag box, specify the tag you want in the following format: <acr-name><image-name>/<tag>, where <acr-name> is the name of the container registry you created. Press Enter.

  3. When the image finishes building, click Refresh at the top of the IMAGES explorer and verify that the image is built successfully.

    Screenshot shows the built image with tag.

Deploy to container registry

  1. In the Activity Bar, click the Docker icon. In the IMAGES explorer, find the image you just built.

  2. Expand the image, right-click on the tag you want, and click Push.

  3. Make sure the image tag begins with <acr-name> and press Enter.

  4. When Visual Studio Code finishes pushing the image to your container registry, click Refresh at the top of the REGISTRIES explorer and verify that the image is pushed successfully.

    Screenshot shows the image deployed to Azure container registry.

Deploy to App Service

  1. In the REGISTRIES explorer, expand the image, right-click the tag, and click Deploy image to Azure App Service.
  2. Follow the prompts to choose a subscription, a globally unique app name, a resource group, and an App Service plan. Choose B1 Basic for the pricing tier, and a region near you.

After deployment, your app is available at http://<app-name>

A Resource Group is a named collection of all your application's resources in Azure. For example, a Resource Group can contain a reference to a website, a database, and an Azure Function.

An App Service Plan defines the physical resources that will be used to host your website. This quickstart uses a Basic hosting plan on Linux infrastructure, which means the site will be hosted on a Linux machine alongside other websites. If you start with the Basic plan, you can use the Azure portal to scale up so that yours is the only site running on a machine. For pricing, see App Service pricing.

Browse the website

The Output panel shows the status of the deployment operations. When the operation completes, click Open Site in the pop-up notification to open the site in your browser.

Next steps

Congratulations, you've successfully completed this quickstart.

The App Service app pulls from the container registry every time it starts. If you rebuild your image, you just need to push it to your container registry, and the app pulls in the updated image when it restarts. To tell your app to pull in the updated image immediately, restart it.

Other Azure extensions: